blackberry push service sdk development guide 925871 0316052041 001 1.0.0.5 us

BlackBerry Push Service SDKVersion: 1.0.0.5

Development Guide

Published: 2010.05.11SWD-925871-0511114345-001

Contents1 Overview of the framework for delivering content to the BlackBerry devices using push technology......................... 4

2 Overview of the BlackBerry Push Service SDK....................................................................................................................... 6

3 Architecture: BlackBerry Push Service framework................................................................................................................. 8

4 Prerequisites for using the BlackBerry Push Service SDK.................................................................................................... 9

5 Application development........................................................................................................................................................... 10

Using the BlackBerry Push Service SDK server-side library components............................................................................... 10

Dependencies among the BlackBerry Push Service SDK server-side library components........................................... 11

Using the low-level API functionalities............................................................................................................................... 12

Technology stack: BlackBerry Push Service SDK low-level APIs............................................................................. 12

Using the high-level API functionalities.............................................................................................................................. 13

Technology stack: BlackBerry Push Service SDK high-level APIs............................................................................ 14

The Commons component..................................................................................................................................................... 15

The PAP component............................................................................................................................................................... 15

The Push Application Management component................................................................................................................ 16

The Subscription component................................................................................................................................................ 16

The Push component............................................................................................................................................................. 17

The Acknowledgment component........................................................................................................................................ 17

Application feature development paradigms for the Push Initiator......................................................................................... 18

Push Plus Reconciled paradigm........................................................................................................................................... 18

Push Plus Unreconciled paradigm....................................................................................................................................... 18

Push Essentials paradigm...................................................................................................................................................... 19

Helper applications......................................................................................................................................................................... 19

Using the DebugPortal.......................................................................................................................................................... 20

System requirements and library dependencies: DebugPortal................................................................................ 21

Configure the BlackBerry Push Service SDK to run in public or enterprise mode................................................. 21

Specify the base URL for the PPG................................................................................................................................ 21

Configure the properties related to push.................................................................................................................... 22

Configuration properties related to push.................................................................................................................... 22

Specify the configuration properties for the database.............................................................................................. 24

Configuration properties for the database................................................................................................................. 24

Specify the base URL for subscription deregistration, suspend, and resume......................................................... 26

Configure the properties related to the log file and logging.................................................................................... 27

Configure the Commons component.......................................................................................................................... 27

Configurations for the Commons component............................................................................................................ 27

Configure the PAP component..................................................................................................................................... 30

Configure the Push Application Management Component..................................................................................... 31

Configurations for the Push Application Management component........................................................................ 31

Configure the Push component................................................................................................................................... 33

Configurations for the Push component..................................................................................................................... 33

Configure the Subscription component...................................................................................................................... 36

Configurations for the Subscription component........................................................................................................ 36

Configure the properties for actions related to subscription and subscribers....................................................... 40

Configuration properties for actions related to subscription and subscribers....................................................... 40

Configure the properties of the net.rim.pushsdk.commons.http.HttpClientImpl class........................................ 42

Configuration properties of the net.rim.pushsdk.commons.http.HttpClientImpl class........................................ 42

Configure the properties related to the

net.rim.pushframework.acknowledgement.AcknowledgementManager class...................................................... 43

Configuration properties related to the


Using the PushSDK................................................................................................................................................................ 44

System requirements and library dependencies: PushSDK...................................................................................... 45



Configure the properties related to push.................................................................................................................... 46

Configuration properties related to push.................................................................................................................... 46

Specify the configuration properties for the database.............................................................................................. 48

Configuration properties for the database................................................................................................................. 48





Configure the Push Application Management Component..................................................................................... 55

Configurations for the Push Application Management component........................................................................ 55

Configure the Push component................................................................................................................................... 57

Configure the Subscription component...................................................................................................................... 57

Configurations for the Subscription component........................................................................................................ 57

Configure the properties for actions related to subscription and subscribers....................................................... 61

Configuration properties for actions related to subscription and subscribers....................................................... 61

Configure the properties of the net.rim.pushsdk.commons.http.HttpClientImpl class........................................ 63

Configuration properties of the net.rim.pushsdk.commons.http.HttpClientImpl class........................................ 63

Configure the properties related to the


Configuration properties related to the


Using the PAPNotify.............................................................................................................................................................. 65

System requirements and library dependencies: PAPNotify.................................................................................... 66







6 Glossary......................................................................................................................................................................................... 72

7 Provide feedback......................................................................................................................................................................... 73

8 Legal notice.................................................................................................................................................................................. 74

Overview of the framework for delivering content to theBlackBerry devices using push technology

1

The framework which enables a server-initiated delivery of content to the BlackBerry® devices, by using push technology, is aclient/server model. Pull technology waits for the devices to make a request to your server to send content. In contrast, pushtechnology enables your server to initiate the content delivery to the devices without any requests for content coming from thedevices.

The framework includes the protocols, the service interfaces, the hardware entities, and the software entities that provide youthe means to deliver content to the BlackBerry devices.

Category Component Description

software entities Push Initiator the software entity that originates the content

and submits it to the framework for delivery

Push-enabled application the software entity that interprets and displays

the content to the user

service interface Push Proxy Gateway the entity that provides services similar to a proxy

server and also works as the gateway to the

wireless network for the content by acting as an

access point, delivering the content to its final

destination

hardware entities Push Server the hardware entity that hosts the software (Push

Initiator) that originates the content for

submission to the framework

Push Client the hardware entity that hosts the software

(Push-enabled application) that interprets and

displays the content to the user

Development Guide Overview of the framework for delivering content to the BlackBerry devices using push technology

4

Category Component Description

protocols PAP the protocol that the Push Initiator uses to submit

the content and the push related control

information to the Push Proxy Gateway

IPPP the protocol that the Push Proxy Gateway uses

to deliver the content to the BlackBerry devices

(Push Clients)

Development Guide Overview of the framework for delivering content to the BlackBerry devices using push technology

5

Overview of the BlackBerry Push Service SDK 2

The BlackBerry® Push Service SDK contains a set of Java® libraries you can use to develop push applications. It consists of aserver-side library that exposes the push functionalities of the Push Proxy Gateway at a higher level so that you can focus ondeveloping the features of your push application, instead of spending time to learn how to accomplish infrastructure related tasks.

The libraries are designed to handle complex use cases and implement best practices, thereby removing the need for you to writeboilerplate code. They provide a consistent programming model that you can follow to develop Push Initiators. The server-sidelibrary is componentized. There are dependencies among the components and choosing one component might mean you needto use one or more of the other components. Typical usage involves either using the components that provide low-level APIfunctionalities or using the components that provide high-level API functionalities.

You can configure the BlackBerry Push Service SDK for public mode or enterprise mode. Public mode allows you to develop pushapplications that use the BlackBerry® Push Service in the BlackBerry® Infrastructure to deliver content to anyone who subscribesto your push service (you must register with Research In Motion to use the BlackBerry Push Service). Enterprise mode allows youto develop push applications that use the BlackBerry® Enterprise Server to deliver content to the members of your organizationonly.

To create a content delivery solution using the push technology, you need to develop both the Push Initiator (that is, the applicationthat submits push requests to the Push Proxy Gateway) on the server side, and a push-enabled application (that is, the applicationon the BlackBerry device that receives the content) on the client-side. A client-side library (the Push API, located in thenet.rim.blackberry.api.push package) is available in the BlackBerry Java Development Environment 5.0 or later tohelp you develop push-enabled applications for the BlackBerry device. The client-side library is designed to provide themechanisms for building standard features into your push-enabled application and optimize the performance of the applicationon the device.

The BlackBerry Push Service SDK solution provides the following:

Component Description

server-side library The server-side library provides the following components: Commons, PAP, Push,

Push Application Management, Subscription, and Acknowledgment.

client-side library Available in BlackBerry JDE 5.0 or later, the Push API in the

net.rim.blackberry.api.push package provides push-enabled

applications, that use the BlackBerry Push Service SDK, with connectivity

management and application performance optimization functionalities.

helper applications These applications are complete web applications or web application templates that

demonstrate or can be modified to use the functionalities of the BlackBerry Push

Service SDK server-side library: DebugPortal, PushSDK, and PAPNotify.

Development Guide Overview of the BlackBerry Push Service SDK

6


sample applications The sample Push Initiator demonstrates the use of the BlackBerry Push Service SDK

and the sample push-enabled application demonstrates the use of the Push API

from the client-side library.

Development Guide Overview of the BlackBerry Push Service SDK

7

Architecture: BlackBerry Push Service framework 3

Development Guide Architecture: BlackBerry Push Service framework

8

Prerequisites for using the BlackBerry Push Service SDK 4

To use the BlackBerry® Push Service SDK, be aware of the following considerations:

• You must identify the following requirements for your push application:• whether it will use the BlackBerry® Internet Service or a BlackBerry® Enterprise Server as the Push Proxy Gateway to

push content• the number of daily pushes• the size of the file or content that the Push Initiator submits to the push framework

• If your push framework uses the BlackBerry® Internet Service as the PPG to push content, you must register your pushapplication with Research In Motion. To register, visit www.blackberry.com/profile/?eventId=push_api.

• To create a complete push solution, you must develop the following components:• the Push Initiator (that is, the application that submits push requests to the Push Proxy Gateway) for the server side• a push-enabled application (that is, the application on the BlackBerry device that receives push content) for the client-

side

Development Guide Prerequisites for using the BlackBerry Push Service SDK

9

https://www.blackberry.com/profile/?eventId=push_api

Application development 5

Using the BlackBerry Push Service SDK server-side library componentsBased on functions, the server-side library is divided into multiple components. A component is a logical collection of APIs thatprovide functionalities for accomplishing some related tasks with regards to developing a Push Initiator. Each component isprovided as a .jar file. You might choose to use any of the components. However, there are dependencies among the componentsand choosing one component might mean you need to use one or more of the other components.

The components can be further categorized into two groups, one providing low-level API functionalities and the other providinghigh-level API functionalities. You can choose to use either of these categories. The choice is based on your development needsand approach.

• components providing low-level API functionalities: Commons, PAP• components providing high-level API functionalities: Push Application Management, Subscription, Push, Acknowledgment


Commons provides APIs whose functionality can be shared across the other components, such

as APIs for handling root level exceptions, HTTP client implementation, validation,

string manipulation, date manipulation, random data generation, and so on

PAP provides APIs for creating, sending, receiving, and parsing PAP messages

Push Application Management provides APIs for managing attributes of the push applications and for storing push

applications in a persistent store

Subscription contains servlets for handling subscribe, unsubscribe, suspend, and resume

operations, APIs for retrieving counts and statistics, and so on

Push provides APIs to manage all aspects of a push, such as validating and sending push

messages, cancelling previously submitted messages, querying the status of

previously submitted messages, reconciling push acknowledgments, persisting the

status of push operations, and so on

Acknowledgment contains servlets for listening to result notification messages and sending result

notification response messages to the PPG, APIs for reconciling the result

notification messages with the push request details, and so on

Development Guide Application development

10

Dependencies among the BlackBerry Push Service SDK server-side library components

The interdependencies among the BlackBerry® Push Service SDK server-side library components mean that when you chooseto use one component you might need to use one or more of the other components based on the dependencies. The dependenciesamong the components are depicted in the diagram below. It is drawn with the simplification that if B depends on C and Adepends on B and C, it is not necessary to represent the dependency of A on C, since it is already implied. As shown in thisdiagram, all components are dependent on the Commons component and the Acknowledgment component is dependent on allthe other components.

Development Guide Using the BlackBerry Push Service SDK server-side library components

11

Using the low-level API functionalities

You can choose to only use the low-level API functionalities of the BlackBerry Push Service SDK server-side library through theCommons and the PAP components. These functionalities create a thin but simple and effective Java API layer in front of PAPXML which removes the need for you to write and parse PAP XML and multipart MIME messages. Typically, you would use thelow-level API functionalities only when your own Push Initiator is handling push requests, subscriptions, and acknowledgements.

Technology stack: BlackBerry Push Service SDK low-level APIs


12

Using the high-level API functionalities

You can choose to use only the high-level API functionalities of the BlackBerry® Push Service SDK server-side library throughthe Push Application Management, Subscription, Push, and Acknowledgement components. These functionalities are built ontop of the low-level API functionalities that are provided by the Commons and the PAP component. The high-level APIfunctionalities provide many value added features, as compared to the low-level API functionalities, and require the use of adatabase. Typically, you would use the high-level API functionalities only when your own Push Initiator is not handling pushrequests, subscriptions, and acknowledgements. Your application only needs to be able to generate or retrieve the content thatneeds to be pushed and the subscriber to whom it is going to be pushed, when using the high-level API functionalities. The restis taken care of by the Push Application Management, Subscription, Push, and Acknowledgement components.


13

Technology stack: BlackBerry Push Service SDK high-level APIs


14

The Commons component

The Commons component is designed to provide the functionalities that can be shared across the other components of theBlackBerry® Push Service SDK server-side library. The Commons component contains base classes, base exceptions, utility classes,and helper classes providing functionalities such as handling root level exceptions, HTTP client implementation, validation, stringmanipulation, date manipulation, and random data generation. The database schema files are located in this component. TheCommons component has 2 subpackages: content and http.

Subpackage Description

content models content sent in push requests

http defines an HTTP client

The PAP component

The PAP component is designed to provide the functionalities for you to create, send, receive, and parse PAP messages. It includesclasses that represent the PAP status codes, PAP control objects, a servlet that unmarshals the result notification messages andsends the confirmation to the PPG, enums that represent the PAP message state and message reliability, and an exception thathandles the rejection of PAP messages by the PPG.

The PAP component hides the details of the PAP and MIME messaging. Instead of using PAP XML directly, you can use the Java®interface that is available in this component to develop and test your push applications. The PAP component offers low-level APIfunctionalities that can provide flexible usage and greater control over implementation. For a high-level API that offers manyvalue added services, you can use the Push component instead.

The PAP component has 3 subpackages: control, unmarshal, and web.


control implements PAP control messages

unmarshal implements PAP message unmarshalling

web contains an abstract servlet to receive and handle PAP result notification messages

and to send result notification response messages to the PPG


15

The Push Application Management component

The Push Application Management component is designed to provide the functionalities for you to manage the attributes of thepush applications and store push applications in a persistent store. The Push Application Management component lets you add,update, enable, disable, delete, or query for applications by using attributes such as the application name, application ID,application status and so on. Push application attributes, passed as parameters to the methods that perform the add, update,enable, disable, and delete application operations as well as update credentials operations, are validated to make sure that theysatisfy the validation criterion for the action performed by the methods. An exception is thrown if any of the criteria is not met.

By managing the push application attributes, the Push Application Management component enables the method that performsthe push operation, located in the Push component, to only use the push application ID to retrieve the push application's attributesfrom the persistent store. The push application's attributes, such as the listening port number, password, default push messagetime to live, default reliability, and so on can be automatically included as part of the PAP push message.

The Subscription component

The Subscription component is designed to handle the subscription related operations: subscribe, unsubscribe, suspend, andresume. Handling subscription operations requires persistence. The Subscription component provides the implementation fordatabase persistence.

The subscription related operations are handled by servlets. When a request for one of these operations come into the specificservlet, the request information is validated and processed and then persisted to the database. If you are not using container-managed security, the component can provide the functionalities for your server side application to authenticate users and canhandle exceptions related to user authentication. You can customize the authentication process to use extra properties in additionto username and password to authenticate users and can also take custom actions on subscribe, unsubscribe, resume, and suspendevents. Usernames and passwords can support international characters if configured through the HTTP header or the applicationserver configuration settings.

The Subscription component includes find methods and methods to retrieve counts and statistics, to manage subscribers andfor reporting purposes. If you assign a unique subscriber ID to each user, the Subscription component will try to detect when asubscriber to your applications has changed on a given device or when a particular subscriber to your applications has moved toanother device. These scenarios are detected through new subscription requests coming from a user or device already existingin your subscriber database. Upon detection, the component triggers an automatic unsubscribe of the users, involved in thescenarios and who have already been your subscriber, from their existing subscriptions to your applications, while fulfilling thenew subscription request.

There are 3 subpackages in this component: auth, cp, and web.


auth handles subscriber authentication


16


cp provides the ability to take custom actions on subscription events

web contains servlets to handle subscription operations

The Push component

The Push component is designed to provide the functionalities to manage all aspects of a push: validate and send push messages,cancel previously submitted messages, query the status of previously submitted messages, reconcile push acknowledgements,and persist the status of a push.

The Push component is designed as a layer on top of the PAP component. The Push component provides simple PAP messagingcapabilities similar to those available in the PAP component. The Push component also provides value added services such asvalidation and persistence. The Push component is designed to hide the use of PAP. It is also designed to enable you to usesubscriber IDs, instead of BlackBerry® device PINs or email addresses, when you use the BlackBerry® Push Service SDK server-side APIs. Functionalities for mapping subscriber IDs to BlackBerry device PINs or email addresses and vice versa are also available.

The Acknowledgment component

The Acknowledgment component is designed to manage result notification messages and result notification response messages,collectively referred to as acknowledgments. It listens for result notification messages from the PPG regarding the successful orunsuccessful delivery of the push messages to the BlackBerry® devices and, depending on the type of the push application,reconciles the result notification messages with the push request details. The Acknowledgment component also sends resultnotification response messages to the PPG confirming the delivery of the result notification messages.

The Acknowledgment component is dependent on the PAP, Push, and Subscription components. The Acknowledgmentcomponent uses the PAP component to parse the PAP XML of the result notification messages and to construct the PAP XML ofthe result notification response messages. The Acknowledgment component uses the Push component to perform reconciliationof the push messages, that is, updating the status of the addresses being pushed to. The Acknowledgment component uses theSubscription component to map the addresses in the PAP messages (for example, the PINs to subscriber IDs). This mapping isuseful when you want to be notified of the acknowledgments so that you can take custom actions in your Push Initiator.

You can use the Acknowledgment component in one of three different ways. Firstly, you can use it to listen and parse theacknowledgments into simple Java® objects that can be handed off to the Push Initiator which utilizes the BlackBerry® PushService SDK for further processing. Secondly, you can have it listen, parse, and reconcile the acknowledgments within theBlackBerry Push Service SDK so that any user of the BlackBerry Push Service SDK can call one of the query APIs to get the currentstatus of a push request. Thirdly, you can use it to not only listen and reconcile the acknowledgments but also notify severallisteners that process certain types of notification messages based on the status code of the messages: success, failure, any, orlast notification from the original push request. By using it the third way, you can subclass the listener classes to create customimplementations of the methods, to further process the acknowledgments in your Push Initiator.


17

The Acknowledgment component contains only the web subpackage which has the servlet that unmarshals the result notificationmessages and constructs and sends result notification response messages to the PPG.

Application feature development paradigms for the Push InitiatorThere are three application feature development paradigms when developing your Push Initiator using the BlackBerry® PushService SDK. The paradigms refer to the conceptual models that can be ascribed to the features of a Push Initiator based on howthose features handle result notifications and content delivery statuses, and perform subscription maintenance. These threeparadigms are the Push Plus Reconciled paradigm, the Push Plus Unreconciled paradigm, and the Push Essentials paradigm.

Push Plus Reconciled paradigm

Features of your Push Initiator can be ascribed to the Push Plus Reconciled paradigm only if you develop those features to workwith a push-enabled application that is going to be configured with the Push Plus service level at the PPG.

In the Push Plus Reconciled paradigm you develop your Push Initiator features to use the BlackBerry® Push Service SDK server-side library for reconciliation of the content delivery status between the PPG and the Push Initiator database. You perform thereconciliation by developing Push Initiator features that uses the server-side library to save the details of a push submission inthe Push Initiator database and, upon receiving the result notification message from the PPG, update the Push Initiator databasewith the statuses of the content delivery attempts to the subscribers. In this paradigm you develop your Push Initiator featuresto also use the server-side library for performing subscription maintenance.

In summary, features of your Push Initiator that are associated with the Push Plus Reconciled paradigm uses the server-sidelibrary to:

• save the details of the Push submissions to the database,• receive result notification messages from the PPG,• process the result notification messages,• determine the final outcome of the PPG's attempts at delivering the content to the subscribers using the information

obtained from the result notification messages,• update the details of the push submissions stored in the Push Initiator database based on the final outcome of the content

delivery attempts,• determine the subscription status changes and errors using the information obtained from the result notification messages,

and• perform subscription maintenance using the information.

Push Plus Unreconciled paradigm

Features of your Push Initiator can be ascribed to the Push Plus Unreconciled paradigm only if you develop those features towork with a push-enabled application that is going to be configured with the Push Plus service level at the PPG.

Development Guide Application feature development paradigms for the Push Initiator

18

In the Push Plus Unreconciled paradigm you develop your Push Initiator features to use the BlackBerry® Push Service SDK server-side library only for performing subscription maintenance. You do not develop your Push Initiator features to use the server-sidelibrary for reconciliation of the content delivery status between the PPG and the Push Initiator database. You might choose toperform the reconciliation by developing Push Initiator features that uses custom development solutions to save the details of apush submission in the Push Initiator database and, upon receiving the result notification message from the PPG, update thePush Initiator database with the statuses of the content delivery attempts to the subscribers, without the use of the server-sidelibrary.

In summary, using the server-side library, your Push Initiator features associated with the Push Plus Unreconciled paradigm:

• receive result notification messages from the PPG,• process the result notification messages,• determine the subscription status changes and errors using the information obtained from the result notification messages,• perform subscription maintenance.

Push Essentials paradigm

Features of your Push Initiator can be ascribed to the Push Essentials paradigm only if you develop those features to work witha push-enabled application that is going to be configured with the Push Essential service level at the PPG.

In the Push Essentials paradigm you do not develop your Push Initiator features to use the BlackBerry® Push Service SDK server-side library for reconciliation of the content delivery status between the PPG and the Push Initiator database. Because resultnotification is not available in the Push Essentials service level, reconciliation cannot be performed using the server-side library.When using this paradigm it is suggested that you perform subscription maintenance using custom development solutions.

Helper applicationsThe BlackBerry® Push Service SDK includes a number helper applications: complete, or partially complete, web applicationtemplates that you can use to quickly access some of the features of the BlackBerry Push Service SDK with little or no developmenteffort. Helper applications are available in WAR file format.

The BlackBerry Push Service SDK includes the following helper applications:

Helper application Description

DebugPortal a complete Push Initiator that helps demonstrate some of the key features of the BlackBerry

Push Service SDK server-side library by enabling quick setup and test run of "Hello World"

type push-enabled applications or helping to debug and test production grade push-enabled

applications

Development Guide Helper applications

19

Helper application Description

PushSDK a web application that helps deploy the default implementations of the servlets from the

Acknowledgement component to capture acknowledgements from the PPG, and the

Subscription component to capture subscription requests from the device, when you use only

the high-level API functionalities of the BlackBerry Push Service SDK server-side library

PAPNotify a web application template that helps deploy an implementation of the abstract servlet from

the PAP component to capture acknowledgements from the PPG, when you use only the

low-level API functionalities of the BlackBerry Push Service SDK

Using the DebugPortal

You can use the DebugPortal web application to test some of the key features of the BlackBerry® Push Service SDK server-sidelibrary. You can also use it to test and debug your push applications or to quickly run a test "Hello World" application. TheDebugPortal is not designed for use in a production environment as it does not include security features such as login, data fieldhiding, role based permissions and so on. It is not designed to handle a large volume of queries due to lack of paging support.

The DebugPortal web application has a simple UI. This UI is designed to help you administer and test your push applications,until you have created your own UI on top of the BlackBerry Push Service SDK server-side APIs to use in a production environment.Leveraging the features of the APIs, form fields in the DebugPortal web application are validated on the server side upon formsubmission. Any field validation errors or errors relating to the business logic are presented on the form submission page. Typicalvalidation checks include ensuring that mandatory fields are specified and that field lengths do not exceed the allowablemaximums. Fields that are non-alphanumeric, like integers or dates, are checked to ensure that their format is correct for thedata type. Business rules, for example, "If Store Push Request checkbox is set to true then the Notify URL field must be specified.",are also checked.

You can perform the following tasks using the DebugPortal.

• add a push application• send a push request• query the status of previously submitted push requests by using various criteria• update or delete a push application• update push application credentials or push application status• list all push applications• suspend or resume a subscription• unsubscribe a subscriber• view the subscribers of a push application• view the characteristics of a specific subscriber


20

System requirements and library dependencies: DebugPortal

Type Details

system requirements • JRE™ version 6 or later

• any JSP 2.1 servlet container (Apache Tomcat™ 6 or later is suggested) that

implements Java® Servlet Specification version 2.5

• relational database, such as MySQL® (MySQL Community Server 5.1.34 or later is

suggested) or Oracle® (Oracle Database 10g Release 2 or later is suggested)

library dependencies • Spring Framework MVC

• all components of the BlackBerry® Push Service SDK server-side library

Configure the BlackBerry Push Service SDK to run in public or enterprise modeIf you use the setup application for the BlackBerry® Push Service SDK and choose the option to install Apache Tomcat™, you donot need to perform this task to use the helper application. To develop a Push Initiator that uses the BlackBerry Push ServiceSDK server-side library components, you need to configure the properties manually by completing this task.

Before you begin: Verify that you have an application to extract and repackage WAR files.

1. Inside the WAR file, in the WEB-INF folder navigate to the classes subfolder.

2. Open the PushSDK.properties file with a text editor.

3. Perform one of the following actions:• To configure the BlackBerry® Push Service SDK to run in public mode, in the General SDK configuration properties

section, set the use.public.push property to true.• To configure the BlackBerry Push Service SDK to run in enterprise mode, in the General SDK configuration

properties section, set the use.public.push property to false.

Specify the base URL for the PPGIn public mode, the PPG address is the address of the BlackBerry® Infrastructure. The BlackBerry® Push Service administratorprovides you with this URL. If you are developing Push Initiators that use the BlackBerry® Enterprise Server for delivering thepush content, you can obtain the PPG address from the BlackBerry Enterprise Server administrator in your organization.




3. Perform one of the following actions:


21

Task Steps

Specify the PPG base URL for public

mode.

In the Push management configuration properties section, for the

ppg.address property, replace the ${ppg.base.url} token with the host name

and port number of the BlackBerry Infrastructure in the following format:

https://<host name>:port number (for example, https://server:9000).

Specify the PPG base URL for

enterprise mode.a. Comment out the line for the ppg.adress property with the $

{ppg.base.url} token by typing a # character at the beginning of the line.

b. Remove the # character from the beginning of the line for the

ppg.address property with the ${bes.ppg.base.url} token.

c. Replace the ${bes.ppg.base.url} token with the host name and port

number of the BlackBerry® MDS Connection Service centralized push

server in the following format: http://<host name>:port number (for

example, http://server:7000).

Configure the properties related to push




3. In the Push management configuration properties section, change the values for the properties you like to modify.

Configuration properties related to push

You can modify the configuration properties related to push in the PushSDK.properties file.

Configuration properties Description

ppg.address This property specifies the push message submission address of the PPG.

You must specify a value for this property.

Note: The push message submission address of the PPG must be an absolute URL.

regenerate.pushid.max.attem

pts

Applicable only when the Store Push Requests attribute of a push-enabled application is set

to true, this property specifies the maximum number of attempts the

net.rim.pushsdk.commons.IdGeneratorImpl.generateId() method gets

to generate a unique Push ID before the push operation is terminated. This also applies if


22


you are using your own implementation of the

net.rim.pushsdk.commons.IdGenerator interface for generating the Push ID.

When the specified number of attempts have failed to generate a unique Push ID and the

push operation terminates, the InvalidPushRequestException is thrown and a

warning is logged.

Default value is 5.

Note: When using the high-level API functionalities, this property is ignored if you set the

Push ID through the net.rim.pushsdk.push.PushParameters.setPushId

(String) method.

default.deliver.before.timesta

mp.offset

Applicable only when you are using the low-level API functionalities, this property specifies

the time period (in milliseconds) within which the push message must be delivered to the

BlackBerry® devices. This also includes any time spent in retry attempts. The time period

starts from the moment when the push operation is started by the PPG. After this time period

is over, the push operation will terminate. When delivering content to a push-enabled

application with Push Plus service level in the SDK Unreconciling paradigm, for each of the

device addresses for which the push message could not be delivered, the

resultnotification-message element of the result notification message will have

"expired" as the value of the message-state attribute.

Default value is 3600000.

Note: This property is ignored when the time period is specified through the

net.rim.pushsdk.pap.control.PushMessageControl

().setDeliverBeforeTimestamp(Date) method.

push.request.detail.find.max.r

esults

This property specifies the maximum number of PushRequestDetail objects that will be

returned by the

net.rim.pushsdk.push.request.PushRequestDetailServiceImpl.find

ByDateRange method, which finds all the PushRequestDetail created within the

period specified in the method's parameters.


Note: If you make this value too large it might exhaust available system memory or negatively

affect system performance.


23

Specify the configuration properties for the databaseIf you use the setup application for the BlackBerry® Push Service SDK, you do not need to perform this task.




3. In the Database configuration properties section, replace all the tokens with values corresponding to your databaseenvironment and the way you like to configure the datasource.

Configuration properties for the database

You can modify the configurations for the database in the PushSDK.properties file.


database.type This property specifies the type of the database that you are using with the BlackBerry®

Push Service SDK.

Default value is mysql.

The possible choices are mysql or oracle.

driver.class.name This property specifies the fully qualified Java® class name of the JDBC driver you are using.


Example of a fully qualified Java class name of a JDBC driver for a MySQL® database is

com.mysql.jdbc.Driver. A similar example for a Oracle® database is

oracle.jdbc.driver.OracleDriver.

db.connection.url This property specifies the connection URL to be passed to your JDBC driver to establish a

connection to the database.


Example of a URL for a MySQL database is jdbc:mysql://localhost:3306/pushsdk. A similar

example for Oracle is jdbc:oracle:thin:@localhost:1522:pushsdk.

db.username This property specifies the connection username to be passed to your JDBC driver to establish

a connection to the database.



24


db.password This property specifies the connection password to be passed to your JDBC driver to establish



db.initialSize This property specifies the initial number of connections that are created when the database

connection pool is started.

The setup application sets the default value to 10. You must specify a value if you are not

using the setup application.

db.maxActive This property specifies the maximum number of active connections that can be allocated

from the database connection pool at the same time.


using the setup application. Specifying a negative value means that there are no limit on

the maximum number of active connections.

db.maxIdle This property specifies the maximum number of connections that can remain idle in the

database connection pool without extra ones being released .



the maximum number of idle connections.

Note: If you specify a value that is too low for heavily loaded systems, it is possible you will

see connections being closed and almost immediately new connections being opened. This

is a result of the active threads momentarily closing connections faster than they are opening

them, causing the number of idle connections to rise above the specified value. The best

value for heavily loaded system will vary but the default value is a good starting point.

db.maxWait This property specifies the maximum duration of time (in milliseconds) that the database

connection pool will wait (when there are no available connections) for a connection to be

returned before throwing an exception.

The setup application sets the default value to 30000. You must specify a value if you are

not using the setup application. Specifying a negative value (for example, -1) means that

the database connection pool will wait indefinitely for a connection to be returned, when

there are no available connections.


25


db.testOnBorrow This property specifies (as a boolean) whether objects are validated before being borrowed

from the database connection pool. If the object fails to validate, it is dropped from the pool

and an attempt is made to borrow another.

The setup application sets the default value to true. You must specify a value if you are not


Note: For the default value (or setting the property to true) to have any effect, the

db.validationQuery property must be set to a non-null string.

db.validationQuery This property specifies the SQL query that will be used to validate connections from the

database connection pool before returning them to the caller.

The setup application sets the default value to SELECT 1 FROM DUAL. You must specify a

value if you are not using the setup application. If you specify a value, it must be a query

that is an SQL SELECT statement which returns at least one row.

Note: Connections are only validated if the db.testOnBorrow property is set to true.

max.in.clause.values This property specifies the maximum number of SQL IN clause parameters allowed by the

database you are using.


For more information about specifying an appropriate value to this property for your

database, see the documentation for the database from your database vendor.

Any configuration properties related to the datasource and the database connection pool that is not specified in thePushSDK.properties file will use the default values of the Apache Commons DBCP. For more information about these configurationproperties and their default values, visit http://commons.apache.org/dbcp/configuration.html

Specify the base URL for subscription deregistration, suspend, and resumeIn public mode, configuring the subscription related properties include specifying the base URL for subscription deregistration,suspend, and resume. This base URL can be the same as the base URL for the PPG. The BlackBerry® Push Service administratorprovides you with this URL. However, if the PPG is set up with a separate infrastructure that is dedicated to subscription, thePPG base URL for subscription is different from the PPG base URL and the BlackBerry Push Service administrator provides youwith both URLs.

If you develop Push Initiators that use the BlackBerry® Enterprise Server for delivering the push content, this configuration doesnot apply.



26



3. In the Subscription configuration properties section, for the <subscription.*.url> properties, replace the ${ppg.sub.base.url} tokens with the host name and port number of the BlackBerry Infrastructure for subscription in thefollowing format: https://<host name>:port number (for example, https://server:9000).

Configure the properties related to the log file and loggingYou need to perform this task to specify the default location of the log file if you do not use the setup application for the BlackBerry®Push Service SDK or use the setup application without the option to install Apache Tomcat™, to use the helper application.Optionally you can perform this task if you want to change the default values for the logging level, date format, and otherproperties related to the log file and logging. To develop a Push Initiator that uses the BlackBerry Push Service SDK server-sidelibrary components, you need to configure the properties manually by completing this task.



2. Open the log4j.xml file with a text editor.

3. Change the values for the properties you like to modify.

Configure the Commons componentYou can perform this optional task to make the Helper application to use a customized Commons component that uses classesyou have written, your own implementation of the interfaces, the transaction manager you would like to use from the Springframework, conditions that you would like to specify for transaction rollback, caching behavior that you would like to configure,and so on.



2. Open the commons-context.xml file with a text editor.


Configurations for the Commons component

You can modify the configurations for the Commons component in the commons-context.xml file.

bean id="transactionManager"<bean id="transactionManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">

<property name="dataSource" ref="dataSource"/></bean>


27

• You can change the default value of the class attribute to specify the transaction manager you want to use from theSpring framework.

• The default value is org.springframework.jdbc.datasource.DataSourceTransactionManager.

tx:advice id="defaultTxnAdvice"<tx:advice id="defaultTxnAdvice" transaction-manager="transactionManager">  <tx:attributes> <tx:method name="get*" read-only="true" propagation="SUPPORTS"/> <tx:method name="find*" read-only="true" propagation="SUPPORTS"/>  <tx:method name="*" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.DataAccessException"/> </tx:attributes></tx:advice>

• You can change the default value of the rollback-for attribute to specify the conditions when a transaction needs tobe rolled back.

• The default value is net.rim.pushsdk.commons.PushSDKException,org.springframework.dao.DataAccessException. This configures the BlackBerry® Push Service SDK to rollback a transaction when any method, except the <get*> or <find*> methods, throws the PushSDKException orDataAccessException.

bean id="propertyConfigurer"<bean id="propertyConfigurer" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">

<property name="locations"> <value>classpath:PushSDK.properties</value> </property></bean>

• You can change the default value of the classpath attribute to specify the property store, which is the file from wherethe BlackBerry® Push Service SDK properties are loaded.

• The default value (filename) is PushSDK.properties.

bean id="pushSDKProperties"<bean id="pushSDKProperties" class="net.rim.pushsdk.commons.PushSDKPropertiesImpl">

<property name="propertyStore" ref="defaultPropertyStore"/></bean>


28

• You can change the default value of the class attribute to specify the class you have created that implements thePushSDKProperties interface.

• The default value net.rim.pushsdk.commons.PushSDKPropertiesImpl points to the default implementationof the interface that is provided with the BlackBerry Push Service SDK.

bean id="defaultPropertyStore"<bean id="defaultPropertyStore" class="net.rim.pushsdk.commons.DefaultPropertyStore"> <property name="timeToLive"> <value>60000</value> </property></bean>

• You can change the default value of the class attribute to specify the class you have created that extends thePropertyStore abstract class to provide a custom property store for storage and caching of the BlackBerry® Push ServiceSDK properties.

• The default value is net.rim.pushsdk.commons.DefaultPropertyStore.

bean id="sqlProperties"<bean id="sqlProperties" class="net.rim.pushsdk.commons.SQLPropertiesImpl"> <property name="pushSDKProperties" ref="pushSDKProperties"/></bean>

• You can change the default value of the class attribute to specify the class you have created that implements theSQLProperties interface.

• The default value net.rim.pushsdk.commons.SQLPropertiesImpl points to the default implementation of theinterface.

bean id="httpClient"<bean id="httpClient" class="net.rim.pushsdk.commons.http.HttpClientImpl"> <property name="pushSDKProperties" ref="pushSDKProperties"/></bean>

• You can change the default value of the class attribute to specify the class you have created that implements theHttpClient interface.

• The default value net.rim.pushsdk.commons.http.HttpClientImpl points to the default implementation ofthe interface.

bean id="application"<bean id="application" class="net.rim.pushsdk.commons.Application"/>


29

• You can change the default value of the class attribute to specify the class you have created to replace theApplication class, which maintains a static reference to the ApplicationContext.

• The default value is net.rim.pushsdk.commons.Application.

bean id="idGenerator"<bean id="idGenerator" class="net.rim.pushsdk.commons.IdGeneratorImpl"/>

• You can change the default value of the class attribute to specify the class you have created that implements theIdGenerator interface.

• The default value net.rim.pushsdk.commons.IdGeneratorImpl points to the default implementation of theinterface.

bean id="cacheManager"<bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean">

<property name="configLocation"> <value>classpath:ehcache.xml</value> </property></bean>

• You can change the default value of the classpath attribute to specify the file from where the CacheManagerconfiguration, that configures the settings related to the caching of PushApplication objects andSubscriberPartial objects, are loaded. The CacheManager is used by the RDBMS data access objects that implementthe PushApplicationDAO and SubscriptionDAO interfaces and therefore the CacheManager configurations affectthe activities of these data access objects.

• The default value (filename) is ehcache.xml.

Configure the PAP componentYou can perform this optional task to make the Helper application use a customized PAP component that uses your ownimplementation of the interfaces.



2. Open the pap-context.xml file with a text editor.


Note: There are dependencies among the configuration files. Some of the properties in this configuration file are just references.To change the values for these properties you have to edit them at their source location.


30

Configure the Push Application Management ComponentYou can perform this optional task to make the Helper application to use a customized Push Application Management componentthat uses your own implementation of the interfaces, settings that you would like to specify for transaction rollback, name youwould like to give to the cache, and so on.



2. Open the push-app-context.xml file with a text editor.



Configurations for the Push Application Management component

You can modify the configurations for the Push Application Management component in the push-app-context.xml file.

aop:config<aop:config> <aop:pointcut id="pushApplicationServiceOperation" expression= "execution(* net.rim.pushsdk.pushappmgmt.PushApplicationServiceImpl.*(. ))"/> <aop:advisor advice-ref="defaultTxnAdvice" pointcut-ref="pushApplicationServiceOperation"/>

</aop:config>

• You can change the default value of the advice-ref attribute to specify the settings that define the methods that aretransactional, the type of transaction propagation that is required per method, and the conditions when a transaction needsto be rolled back.

• The default value is defaultTxnAdvice. This configures all the methods in PushApplicationServiceImpl fortransaction rollback according to the conditions defined in defaultTxnAdvice.

bean id="pushApplicationService"<bean id="pushApplicationService"class="net.rim.pushsdk.pushappmgmt.PushApplicationServiceImpl"> <property name="pushApplicationDAO" ref="pushAppRDBMSDAO"/> <property name="pushSDKProperties" ref="pushSDKProperties"/></bean>


31

• You can change the default value of the ref attribute in property name="pushApplicationDAO" to specify thebean that configures the class you have created that implements the PushApplicationDAO interface.

• The default value is pushAppRDBMSDAO. This configures the Helper application to use a MySQL or an Oracle database.

bean id="pushAppRDBMSDAO"<bean id="pushAppRDBMSDAO"class="net.rim.pushsdk.pushappmgmt.PushAppRDBMSDAOImpl">

<property name="dataSource" ref="dataSource"/> <property name="cache" ref="pushApplicationCache"/> <property name="passwordEncryptorDecryptor" ref="passwordEncryptorDecryptor">

</property> <property name="sqlProperties" ref="sqlProperties"></property></bean>

• You can edit this bean for updating it to configure the class, if you have created your own class, that implements thePushApplicationDAO interface. You can also leave this bean unchanged and create another bean instead.

• The default values configure the default implementation of the PushApplicationDAO interface, thePushAppRDBMSDAOImpl class, to use a cache, an RDBMS database, and a password encryption mechanism.

bean id="passwordEncryptorDecryptor"<bean id="passwordEncryptorDecryptor" class="net.rim.pushsdk.pushappmgmt.DefaultPasswordEncryptorDecryptorImpl">

</bean>

• You can change the default value of the class attribute to specify the class you have created that implements thePasswordEncryptorDecryptor interface.

• The default value net.rim.pushsdk.pushappmgmt.DefaultPasswordEncryptorDecryptorImpl points tothe default implementation of the interface.

bean id="pushApplicationCache"<bean id="pushApplicationCache"class="org.springframework.cache.ehcache.EhCacheFactoryBean">

<property name="cacheManager" ref="cacheManager" /> <property name="cacheName"> <value>net.rim.pushsdk.pushappmgmt.PushAppRDBMSDAOImpl</value> </property></bean>

• You can change the content within the value tags, the child element of <property name="cacheName">, if you wantto specify a different name for the cache. For example, you can set the name of the cache to the class you have created thatimplements the PushApplicationDAO interface. There is no requirements on the format of the name. It could be anyarbitrary string.

• The default cache name is net.rim.pushsdk.pushappmgmt.PushAppRDBMSDAOImpl.


32

Configure the Push componentYou can perform this optional task to make the Helper application to use a customized Push component that uses your ownimplementation of the interfaces, a transaction manager you would like to use instead of the default transaction manager,conditions for transaction rollback that you would like to specify, and so on.

There are dependencies among the configuration files. Some of the properties in this configuration file are only references. Tochange the values for these properties you must edit them at their source location.



2. Open the push-context.xml file with a text editor.


Configurations for the Push component

You can modify the configurations for the Push component in the push-context.xml file.

aop:config<aop:config> <aop:pointcut id="pushServiceOperation" expression="execution(* net.rim.pushsdk.push.PushServiceImpl.*(..))"/> <aop:pointcut id="pushRequestServiceOperation" expression= "execution(* net.rim.pushsdk.push.request.PushRequestServiceImpl.*(..))"/>

<aop:pointcut id="pushRequestDetailServiceOperation" expression="execution (* net.rim.pushsdk.push.request.PushRequestDetailServiceImpl.*(..))"/>

<aop:pointcut id="pushCountServiceOperation" expression= "execution(* net.rim.pushsdk.push.count.PushCountServiceImpl.*(..))"/> <aop:advisor advice-ref="defaultTxnAdvice" pointcut-ref="pushServiceOperation"/> <aop:advisor advice-ref="defaultTxnAdvice" pointcut-ref="pushRequestServiceOperation"/> <aop:advisor advice-ref="defaultTxnAdvice" pointcut-ref="pushRequestDetailServiceOperation"/> <aop:advisor advice-ref="defaultTxnAdvice"


33

pointcut-ref="pushCountServiceOperation"/>

</aop:config>

• You can change the default value of the advice-ref attributes to specify the settings that define the methods that aretransactional, the type of transaction propagation that is required per method, and the conditions when a transaction needsto be rolled back. You can change the default value of the expression attributes to specify the classes that you mighthave created that implements the PushService, PushRequestService, PushRequestDetailService, or thePushCountService interfaces.

• The default value of the advice-ref attributes is defaultTxnAdvice. This configures all the methods in the classesspecified in the expression attributes for transaction rollback, according to the conditions defined indefaultTxnAdvice. The default values of the expression attributes specify the default implementation of thePushService, PushRequestService, PushRequestDetailService, and the PushCountServiceinterfaces.

bean id="pushService"<bean id="pushService"class="net.rim.pushsdk.push.PushServiceImpl"> <property name="subscriptionService" ref="subscriptionService"/> <property name="pushApplicationService" ref="pushApplicationService"/> <property name="pushRequestService" ref="pushRequestService"/> <property name="pushRequestDetailService" ref="pushRequestDetailService"/> <property name="papService" ref="papService"/> <property name="pushSDKProperties" ref="pushSDKProperties"/> <property name="pushIdGenerator" ref="idGenerator"/> <property name="pushCountService" ref="pushCountService"/></bean>

• You can change the default value of the class attribute to specify the class you have created that implements thePushService interface.

• The default value net.rim.pushsdk.push.PushServiceImpl points to the default implementation of theinterface.

bean id="pushRequestService"<bean id="pushRequestService"class="net.rim.pushsdk.push.request.PushRequestServiceImpl">

<property name="pushRequestDAO" ref="pushRequestRDBMSDAO" /> <property name="pushApplicationService" ref="pushApplicationService" />

<property name="pushRequestDetailService"


34

ref="pushRequestDetailService" />

</bean>

• You can change the default value of the class attribute to specify the class you have created that implements thePushRequestService interface.

• The default value net.rim.pushsdk.push.request.PushRequestServiceImpl points to the defaultimplementation of the interface.

bean id="pushRequestRDBMSDAO"<bean id="pushRequestRDBMSDAO"class="net.rim.pushsdk.push.request.PushRequestRDBMSDAOImpl"> <property name="dataSource" ref="dataSource"/> <property name="sqlProperties" ref="sqlProperties"></property> <property name="pushSDKProperties" ref="pushSDKProperties" /></bean>

• You can change the default value of the class attribute to specify the class you have created (for example, to use a relationaldatabase other than MySQL or Oracle, a flat file database, or an in-memory database) that implements thePushRequestDAO interface.

• The default value net.rim.pushsdk.push.request.PushRequestRDBMSDAOImpl points to the defaultimplementation of the interface.

bean id="pushRequestDetailService"<bean id="pushRequestDetailService"class="net.rim.pushsdk.push.request.PushRequestDetailServiceImpl">

<property name="pushRequestDetailDAO" ref="pushRequestDetailRDBMSDAO"/>

<property name="pushSDKProperties" ref="pushSDKProperties"/></bean>

• You can change the default value of the class attribute to specify the class you have created that implements thePushRequestDetailService interface.

• The default value net.rim.pushsdk.push.request.PushRequestDetailServiceImpl points to the defaultimplementation of the interface.

bean id="pushRequestDetailRDBMSDAO"<bean id="pushRequestDetailRDBMSDAO" class="net.rim.pushsdk.push.request.PushRequestDetailRDBMSDAOImpl">

<property name="dataSource" ref="dataSource"/> <property name="sqlProperties" ref="sqlProperties"/> <property name="pushSDKProperties" ref="pushSDKProperties"/></bean>


35

• You can change the default value of the class attribute to specify the class you have created (for example, to use a relationaldatabase other than MySQL or Oracle, a flat file database, or an in-memory database) that implements thePushRequestDetailDAO interface.

• The default value net.rim.pushsdk.push.request.PushRequestDetailRDBMSDAOImpl points to thedefault implementation of the interface.

bean id="pushCountRDBMSDAO"<bean id="pushCountRDBMSDAO"class="net.rim.pushsdk.push.count.PushCountRDBMSDAOImpl">

<property name="dataSource" ref="dataSource"/> <property name="sqlProperties" ref="sqlProperties"/></bean>

• You can change the default value of the class attribute to specify the class you have created (for example, to use a relationaldatabase other than MySQL or Oracle, a flat file database, or an in-memory database) that implements thePushCountDAO interface.

• The default value net.rim.pushsdk.push.count.PushCountRDBMSDAOImpl points to the defaultimplementation of the interface.

Configure the Subscription componentYou need to perform this task if you are not using container-managed authentication, to specify the class that you create toimplement the ContentProviderAuthenticationService interface. Optionally you can perform this task to make theHelper application to use a customized Subscription component that uses your own implementation of the interfaces, a transactionmanager you would like to use instead of the default transaction manager, conditions for transaction rollback that you wouldlike to specify, name you would like to give to the cache, and so on.




2. Open the subscription-context.xml file with a text editor.


Configurations for the Subscription component

You can modify the configurations for the Subscription component in the subscription-context.xml file.

tx:advice id="subscriptionTxnAdvice"<tx:advice id="subscriptionTxnAdvice"transaction-manager="transactionManager">


36

<tx:attributes> <tx:method name="get*" read-only="true" propagation="SUPPORTS"/> <tx:method name="find*" read-only="true" propagation="SUPPORTS"/> <tx:method name="subscribe" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.DataAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/> <tx:method name="unsubscribe" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.Dat aAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/> <tx:method name="suspendSubscription" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.DataAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/> <tx:method name="resumeSubscription" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.Dat aAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/>  <tx:method name="*" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.DataAccessException"/> </tx:attributes></tx:advice>


• The default value for the subscribe, unsubscribe, suspendSubscription, and resumeSubscriptionmethods is net.rim.pushsdk.commons.PushSDKException,org.springframework.dao.DataAccessException,net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException. This configures theBlackBerry® Push Service SDK to roll back a transaction when the subscribe, unsubscribe,suspendSubscription, or the resumeSubscription method throws the PushSDKException,DataAccessException, or the CPSubscriptionFailureException. PushSDKException andDataAccessException is thrown when the business logic in the SDK fails during the subscribe, unsubscribe, suspend,or resume events. The CPSubscriptionFailureException is thrown when your business logic, defined in theimplementation of the ContentProviderSubscriptionService interface, fails during the subscribe, unsubscribe,suspend, or resume events. For all other methods, the default value is


37

net.rim.pushsdk.commons.PushSDKException,org.springframework.dao.DataAccessException. This configures the BlackBerry Push Service SDK to rollback a transaction when any of the other methods, except the <get*> or <find*> methods, throws thePushSDKException or DataAccessException.

aop:config<aop:config> <aop:pointcut id="subscriptionServiceOperation" expression="execution(* net.rim.pushsdk.subscription.SubscriptionServiceImpl.*(..))"/>

<aop:advisor advice-ref="subscriptionTxnAdvice" pointcut-ref="subscriptionServiceOperation"/>

</aop:config>

• You can change the default value of the expression attribute to specify the class you have created that implements theSubscriptionService interface. You can change the advice-ref attribute to specify the transactional advice foruse by the class.

• The default value "execution(* net.rim.pushsdk.subscription.SubscriptionServiceImpl.*(..))" configures the methods in the SubscriptionServiceImpl class to use the subscriptionTxnAdvicetransactional advice.

bean id="subscriptionService"<bean id="subscriptionService"class="net.rim.pushsdk.subscription.SubscriptionServiceImpl">

<property name="pushApplicationService" ref="pushApplicationService" />

<property name="subscriptionDAO" ref="subRDBMSDAO" /> <property name="httpClient" ref="httpClient" /> <property name="pushSDKProperties" ref="pushSDKProperties" /> <property name="contentProviderSubscriptionService" ref="contentProviderSubscriptionService" />

</bean>

• You can change the default value of the class attribute to specify the class you have created that implements theSubscriptionService interface.

• The default value net.rim.pushsdk.subscription.SubscriptionServiceImpl points to the defaultimplementation of the interface.

bean id="subRDBMSDAO"<bean id="subRDBMSDAO"class="net.rim.pushsdk.subscription.SubRDBMSDAOImpl">

<property name="dataSource" ref="dataSource"/>


38

<property name="sqlProperties" ref="sqlProperties"/> <property name="pushSDKProperties" ref="pushSDKProperties"/> <property name="cache" ref="subscriptionCache"/></bean>

• You can change the default value of the class attribute to specify the class you have created (for example, to use a relationaldatabase other than MySQL or Oracle, a flat file database, or an in-memory database) that implements theSubscriptionDAO interface.

• The default value net.rim.pushsdk.subscription.SubRDBMSDAOImpl points to the default implementation ofthe interface.

bean id="subscriptionRequestParser"<bean id="subscriptionRequestParser"class="net.rim.pushsdk.subscription.web.SubscriptionRequestParser">

</bean>

• You can change the default value of the class attribute to specify the class you have created that extends theSubscriptionRequestParser class to support additional HTTP request parameters for use in subscriberauthentication.

• The default value net.rim.pushsdk.subscription.web.SubscriptionRequestParser points to thedefault class that only supports the following properties for use in subscriber authentication: application ID, username,password, and subscription type.

bean id="contentProviderSubscriptionService"<bean id="contentProviderSubscriptionService"class="net.rim.pushsdk.subscription.cp.ContentProviderSubServiceImpl">

</bean>

• You can change the default value of the class attribute to specify the class you have created that implements theContentProviderSubscriptionService interface to take custom actions on subscribe, unsubscribe, suspend, andresume events.

• The default value net.rim.pushsdk.subscription.cp.ContentProviderSubServiceImpl points to thedefault implementation of the interface.

bean id="contentProviderAuthenticationService"<bean id="contentProviderAuthenticationService"class="net.rim.pushsdk.subscription.auth.ContentProviderAuthServiceImpl">

</bean>

• You need to change the default value of the class attribute to specify the class you have created that implements theContentProviderAuthenticationService interface if you are not using container-managed authentication.


39

• The default value net.rim.pushsdk.subscription.auth.ContentProviderAuthServiceImpl points tothe default implementation of the interface.

bean id="subscriptionCache"<bean id="subscriptionCache"class="org.springframework.cache.ehcache.EhCacheFactoryBean">

<property name="cacheManager" ref="cacheManager"/> <property name="cacheName"> <value>net.rim.pushsdk.subscription.SubRDBMSDAOImpl</value> </property></bean>

• You can change the content within the value tags, the child element of <property name="cacheName">, if you wantto specify a different name for the cache. For example, you can set the name of the cache to the class you have created thatimplements the SubscriptionDAO interface. There is no requirements on the format of the name. It could be any arbitrarystring.

• The default cache name is net.rim.pushsdk.subscription.SubRDBMSDAOImpl.

Configure the properties for actions related to subscription and subscribersIf you use the setup application for the BlackBerry® Push Service SDK, you do not need to perform this task.




3. In the Subscription configuration properties section, change the values for the properties you like to modify.

Configuration properties for actions related to subscription and subscribers

You can modify configurations for actions related to subscription and subscribers in the PushSDK.properties file.


subscription.deregistration.url This property specifies the PPG address for deregistering subscribers in public

mode.

Default value is ${ppg.base.url}/mss/PD_cpDeregUser?pin=, where

${ppg.base.url} is a token to be replaced with an actual value.

For example, if the address of the PPG is https://server:9000, then the URL for

deregistering subscribers is https://server:9000/mss/

PD_cpDeregUser?pin=.


40


subscription.suspend.url This property specifies the PPG address for suspending subscriptions in public

mode.

Default value is ${ppg.base.url}/mss/PD_cpSub?

cpAction=suspend&pin=, where ${ppg.base.url} is a token to be

replaced with an actual value.


suspending subscribers is https://server:9000/mss/PD_cpSub?

cpAction=suspend&pin=.

subscription.resume.url This property specifies the PPG address for resuming subscriptions in public mode.


cpAction=resume&pin=, where ${ppg.base.url} is a token to be



resuming subscription is https://server:9000/mss/PD_cpSub?

cpAction=resume&pin=.

subscription.find.max.results This property specifies the maximum limit on the number of results that might be

returned by a subscriber find operation. A large value requires a large amount of

available memory.


subscription.validation.high.water.mar

k

This property specifies the maximum number of subscribers for validation that

determines which optimized query to use. Below this limit, a query optimized for a

small number of users is used. Above this limit, a query optimized for a large number

of users is used.


subscription.validation.batch.size This property specifies the maximum number of subscribers to load at once from

the database for validation. A large value requires a large amount of available

memory. A small value increases the number of calls to the persistent store.


subscription.matching.max.threads This property specifies the maximum number of threads to use for subscription

validation when the number of subscribers is above the limit specified in

subscription.validation.high.water.mark.


41


Default value is 5.

Configure the properties of the net.rim.pushsdk.commons.http.HttpClientImpl classIf you are using an HTTP client other than the one created using the HttpClientImpl class available from the BlackBerry®Push Service SDK, you do not need to perform this task.




3. In the HTTP client configuration properties section, change the values for the properties you like to modify.

Configuration properties of the net.rim.pushsdk.commons.http.HttpClientImpl class

You can modify the configurations for the net.rim.pushsdk.commons.http.HttpClientImpl class in thePushSDK.properties file.


http.connection.timeout This property specifies the duration of time (in milliseconds) allowed in attempting

to establish an HTTP connection to the PPG by an HTTPClientImpl object,

before a timeout error occurs and the connection attempt is terminated.

Default value is 60000, which is equivalent to 1 minute.

Setting this property to 0 means infinite timeout.

http.read.timeout This property specifies the maximum wait time (in milliseconds) allowed for data to

become available for reading from an HTTP connection to the PPG by an

HTTPClientImpl object, before a timeout error occurs and the read action is

terminated.

Default value is 120000, which is equivalent to 2 minutes.


http.is.persistent This property specifies (as a boolean) whether the HTTPClientImpl object uses

a persistent HTTP connection to connect to the PPG.

Default value istrue.


42


Setting this property to true or false might be influenced by performance

expectations of your application and available resources in your server and network

environment.

Configure the properties related to thenet.rim.pushframework.acknowledgement.AcknowledgementManager class




3. In the Acknowledgement configuration properties section, change the values for the properties you like to modify.

Configuration properties related to thenet.rim.pushframework.acknowledgement.AcknowledgementManager class

You can modify the configuration properties related to thenet.rim.pushframework.acknowledgement.AcknowledgementManager class in the PushSDK.properties file.


acknowledgement.manager.r

esult.notification.max.queue.s

ize

This property specifies the size of the internal memory work queue for storing of result

notifications arriving from the PPG. When the queue reaches the maximum size, as specified

through this property, the BlackBerry Push Service SDK starts rejecting the notifications and

the PPG retries to send them at a later time.


Note: If you set a value that is too small, result notifications sent by the PPG will be rejected

by the BlackBerry Push Service SDK and the PPG will retry sending the notifications up to 5

more times, with each retry attempt being delayed longer than the previous attempt. If you

set a value that is too large, the BlackBerry Push Service SDK might use up a lot of system

resources and increase the risk of information loss in the event of a system failure.

acknowledgement.manager.

max.threads

This property specifies the maximum number of AcknowledgementManager threads to

use for processing the result notifications from the internal memory work queue of result

notifications. When a thread is available, it goes to the queue to retrieve a batch of notifications

for processing.


43



Note: If you increase the number of threads and you have adequate system resources

available, it can improve the performance of processing result notifications. When adequate

system resources are not available, increasing the number of threads might degrade the

overall system performance.

acknowledgement.manager.b

atch.size

This property specifies the maximum number of result notifications that an

AcknowledgementManager thread reads as a batch from the internal memory queue of

result notifications and processes all the notifications in the batch at once. When a thread is

available but the total number of notifications in the queue is less than the maximum size of

a batch, as specified through this property, it does not read the batch right away. The thread

waits until the number of accumulated notifications in the queue adds up to the maximum

size of a batch, or waits for a period of time specified by the

acknowledgement.manager.batch.wait.time property, whichever occurs earlier, before it

continues the reading and processing.



atch.wait.time

This property specifies the period of time (in milliseconds) that an available

AcknowledgementManager thread waits when the total number of result notifications

in the internal memory queue of result notifications is less than the maximum size of a batch

specified in the acknowledgement.manager.batch.size property, before the thread continues

the reading and processing of notifications, unless the number of accumulated notifications

in the queue adds up to the maximum size of a batch before the specified waiting period is over.


Note: If result notifications are critical to the functioning of your Push Initiator, you might

choose a smaller value so that the notifications are processed faster.

Using the PushSDK

If you are using the high-level API functionalities of the BlackBerry® Push Service SDK server-side library and want to handleacknowledgments (result notification messages and result notification response messages), you can use the PushSDKconvenience web application to deploy the default implementation of the servlets from the Acknowledgment component andavoid having to create a web application for this purpose. If you want to handle subscription requests (subscribe, unsubscribe,suspend, resume), you can use this web application to deploy the default implementation of the servlets from the Subscriptioncomponent.


44

When you use this web application to handle acknowledgments, you can notify several listeners from the Acknowledgmentcomponent by registering those listeners to be called back to process certain types of notification messages with such statuscodes as: success, failure, any, or last notification from the original push request.

When you use this web application to handle subscription requests, you can provide custom implementations of some interfacesfrom the Subscription component to authenticate subscribers and take certain actions based on successful or failed subscribe,unsubscribe, resume, and suspend events.

System requirements and library dependencies: PushSDK

Type Details




library dependencies • all components of the BlackBerry® Push Service SDK server-side library

Configure the BlackBerry Push Service SDK to run in public or enterprise modeIf you use the setup application for the BlackBerry® Push Service SDK and choose the option to install Apache Tomcat™, you donot need to perform this task to use the helper application. To develop a Push Initiator that uses the BlackBerry Push ServiceSDK server-side library components, you need to configure the properties manually by completing this task.










45




Task Steps


mode.














Configure the properties related to push




3. In the Push management configuration properties section, change the values for the properties you like to modify.

Configuration properties related to push

You can modify the configuration properties related to push in the PushSDK.properties file.


ppg.address This property specifies the push message submission address of the PPG.


Note: The push message submission address of the PPG must be an absolute URL.


46


regenerate.pushid.max.attem

pts

Applicable only when the Store Push Requests attribute of a push-enabled application is set

to true, this property specifies the maximum number of attempts the

net.rim.pushsdk.commons.IdGeneratorImpl.generateId() method gets

to generate a unique Push ID before the push operation is terminated. This also applies if

you are using your own implementation of the

net.rim.pushsdk.commons.IdGenerator interface for generating the Push ID.

When the specified number of attempts have failed to generate a unique Push ID and the

push operation terminates, the InvalidPushRequestException is thrown and a

warning is logged.

Default value is 5.

Note: When using the high-level API functionalities, this property is ignored if you set the

Push ID through the net.rim.pushsdk.push.PushParameters.setPushId

(String) method.

default.deliver.before.timesta

mp.offset

Applicable only when you are using the low-level API functionalities, this property specifies

the time period (in milliseconds) within which the push message must be delivered to the

BlackBerry® devices. This also includes any time spent in retry attempts. The time period

starts from the moment when the push operation is started by the PPG. After this time period

is over, the push operation will terminate. When delivering content to a push-enabled

application with Push Plus service level in the SDK Unreconciling paradigm, for each of the

device addresses for which the push message could not be delivered, the

resultnotification-message element of the result notification message will have

"expired" as the value of the message-state attribute.


Note: This property is ignored when the time period is specified through the

net.rim.pushsdk.pap.control.PushMessageControl

().setDeliverBeforeTimestamp(Date) method.

push.request.detail.find.max.r

esults

This property specifies the maximum number of PushRequestDetail objects that will be

returned by the

net.rim.pushsdk.push.request.PushRequestDetailServiceImpl.find

ByDateRange method, which finds all the PushRequestDetail created within the

period specified in the method's parameters.



47


Note: If you make this value too large it might exhaust available system memory or negatively

affect system performance.

Specify the configuration properties for the databaseIf you use the setup application for the BlackBerry® Push Service SDK, you do not need to perform this task.




3. In the Database configuration properties section, replace all the tokens with values corresponding to your databaseenvironment and the way you like to configure the datasource.

Configuration properties for the database

You can modify the configurations for the database in the PushSDK.properties file.


database.type This property specifies the type of the database that you are using with the BlackBerry®

Push Service SDK.

Default value is mysql.

The possible choices are mysql or oracle.

driver.class.name This property specifies the fully qualified Java® class name of the JDBC driver you are using.


Example of a fully qualified Java class name of a JDBC driver for a MySQL® database is

com.mysql.jdbc.Driver. A similar example for a Oracle® database is

oracle.jdbc.driver.OracleDriver.

db.connection.url This property specifies the connection URL to be passed to your JDBC driver to establish a

connection to the database.


Example of a URL for a MySQL database is jdbc:mysql://localhost:3306/pushsdk. A similar

example for Oracle is jdbc:oracle:thin:@localhost:1522:pushsdk.


48


db.username This property specifies the connection username to be passed to your JDBC driver to establish



db.password This property specifies the connection password to be passed to your JDBC driver to establish



db.initialSize This property specifies the initial number of connections that are created when the database

connection pool is started.



db.maxActive This property specifies the maximum number of active connections that can be allocated

from the database connection pool at the same time.



the maximum number of active connections.

db.maxIdle This property specifies the maximum number of connections that can remain idle in the

database connection pool without extra ones being released .



the maximum number of idle connections.

Note: If you specify a value that is too low for heavily loaded systems, it is possible you will

see connections being closed and almost immediately new connections being opened. This

is a result of the active threads momentarily closing connections faster than they are opening

them, causing the number of idle connections to rise above the specified value. The best

value for heavily loaded system will vary but the default value is a good starting point.

db.maxWait This property specifies the maximum duration of time (in milliseconds) that the database

connection pool will wait (when there are no available connections) for a connection to be

returned before throwing an exception.


49


The setup application sets the default value to 30000. You must specify a value if you are

not using the setup application. Specifying a negative value (for example, -1) means that

the database connection pool will wait indefinitely for a connection to be returned, when

there are no available connections.

db.testOnBorrow This property specifies (as a boolean) whether objects are validated before being borrowed

from the database connection pool. If the object fails to validate, it is dropped from the pool

and an attempt is made to borrow another.

The setup application sets the default value to true. You must specify a value if you are not


Note: For the default value (or setting the property to true) to have any effect, the

db.validationQuery property must be set to a non-null string.

db.validationQuery This property specifies the SQL query that will be used to validate connections from the

database connection pool before returning them to the caller.

The setup application sets the default value to SELECT 1 FROM DUAL. You must specify a

value if you are not using the setup application. If you specify a value, it must be a query

that is an SQL SELECT statement which returns at least one row.

Note: Connections are only validated if the db.testOnBorrow property is set to true.

max.in.clause.values This property specifies the maximum number of SQL IN clause parameters allowed by the

database you are using.


For more information about specifying an appropriate value to this property for your

database, see the documentation for the database from your database vendor.

Any configuration properties related to the datasource and the database connection pool that is not specified in thePushSDK.properties file will use the default values of the Apache Commons DBCP. For more information about these configurationproperties and their default values, visit http://commons.apache.org/dbcp/configuration.html


50















51













bean id="sqlProperties"


52

<bean id="sqlProperties" class="net.rim.pushsdk.commons.SQLPropertiesImpl"> <property name="pushSDKProperties" ref="pushSDKProperties"/></bean>













<property name="configLocation">


53

<value>classpath:ehcache.xml</value> </property></bean>









Configure the properties related to the log file and loggingYou need to perform this task to specify the default location of the log file if you do not use the setup application for the BlackBerry®Push Service SDK or use the setup application without the option to install Apache Tomcat™, to use the helper application.Optionally you can perform this task if you want to change the default values for the logging level, date format, and otherproperties related to the log file and logging. To develop a Push Initiator that uses the BlackBerry Push Service SDK server-sidelibrary components, you need to configure the properties manually by completing this task.






54

Configure the Push Application Management ComponentYou can perform this optional task to make the Helper application to use a customized Push Application Management componentthat uses your own implementation of the interfaces, settings that you would like to specify for transaction rollback, name youwould like to give to the cache, and so on.



2. Open the push-app-context.xml file with a text editor.



Configurations for the Push Application Management component

You can modify the configurations for the Push Application Management component in the push-app-context.xml file.

aop:config<aop:config> <aop:pointcut id="pushApplicationServiceOperation" expression= "execution(* net.rim.pushsdk.pushappmgmt.PushApplicationServiceImpl.*(. ))"/> <aop:advisor advice-ref="defaultTxnAdvice" pointcut-ref="pushApplicationServiceOperation"/>

</aop:config>

• You can change the default value of the advice-ref attribute to specify the settings that define the methods that aretransactional, the type of transaction propagation that is required per method, and the conditions when a transaction needsto be rolled back.

• The default value is defaultTxnAdvice. This configures all the methods in PushApplicationServiceImpl fortransaction rollback according to the conditions defined in defaultTxnAdvice.

bean id="pushApplicationService"<bean id="pushApplicationService"class="net.rim.pushsdk.pushappmgmt.PushApplicationServiceImpl"> <property name="pushApplicationDAO" ref="pushAppRDBMSDAO"/> <property name="pushSDKProperties" ref="pushSDKProperties"/></bean>


55

• You can change the default value of the ref attribute in property name="pushApplicationDAO" to specify thebean that configures the class you have created that implements the PushApplicationDAO interface.

• The default value is pushAppRDBMSDAO. This configures the Helper application to use a MySQL or an Oracle database.

bean id="pushAppRDBMSDAO"<bean id="pushAppRDBMSDAO"class="net.rim.pushsdk.pushappmgmt.PushAppRDBMSDAOImpl">

<property name="dataSource" ref="dataSource"/> <property name="cache" ref="pushApplicationCache"/> <property name="passwordEncryptorDecryptor" ref="passwordEncryptorDecryptor">

</property> <property name="sqlProperties" ref="sqlProperties"></property></bean>

• You can edit this bean for updating it to configure the class, if you have created your own class, that implements thePushApplicationDAO interface. You can also leave this bean unchanged and create another bean instead.

• The default values configure the default implementation of the PushApplicationDAO interface, thePushAppRDBMSDAOImpl class, to use a cache, an RDBMS database, and a password encryption mechanism.

bean id="passwordEncryptorDecryptor"<bean id="passwordEncryptorDecryptor" class="net.rim.pushsdk.pushappmgmt.DefaultPasswordEncryptorDecryptorImpl">

</bean>

• You can change the default value of the class attribute to specify the class you have created that implements thePasswordEncryptorDecryptor interface.

• The default value net.rim.pushsdk.pushappmgmt.DefaultPasswordEncryptorDecryptorImpl points tothe default implementation of the interface.

bean id="pushApplicationCache"<bean id="pushApplicationCache"class="org.springframework.cache.ehcache.EhCacheFactoryBean">

<property name="cacheManager" ref="cacheManager" /> <property name="cacheName"> <value>net.rim.pushsdk.pushappmgmt.PushAppRDBMSDAOImpl</value> </property></bean>

• You can change the content within the value tags, the child element of <property name="cacheName">, if you wantto specify a different name for the cache. For example, you can set the name of the cache to the class you have created thatimplements the PushApplicationDAO interface. There is no requirements on the format of the name. It could be anyarbitrary string.

• The default cache name is net.rim.pushsdk.pushappmgmt.PushAppRDBMSDAOImpl.


56

Configure the Push componentYou can perform this optional task to make the Helper application to use a customized Push component that uses your ownimplementation of the interfaces, a transaction manager you would like to use instead of the default transaction manager,conditions for transaction rollback that you would like to specify, and so on.




2. Open the push-context.xml file with a text editor.


Configure the Subscription componentYou need to perform this task if you are not using container-managed authentication, to specify the class that you create toimplement the ContentProviderAuthenticationService interface. Optionally you can perform this task to make theHelper application to use a customized Subscription component that uses your own implementation of the interfaces, a transactionmanager you would like to use instead of the default transaction manager, conditions for transaction rollback that you wouldlike to specify, name you would like to give to the cache, and so on.




2. Open the subscription-context.xml file with a text editor.


Configurations for the Subscription component

You can modify the configurations for the Subscription component in the subscription-context.xml file.

tx:advice id="subscriptionTxnAdvice"<tx:advice id="subscriptionTxnAdvice"transaction-manager="transactionManager">  <tx:attributes> <tx:method name="get*" read-only="true" propagation="SUPPORTS"/>


57

<tx:method name="find*" read-only="true" propagation="SUPPORTS"/> <tx:method name="subscribe" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.DataAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/> <tx:method name="unsubscribe" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.Dat aAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/> <tx:method name="suspendSubscription" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.DataAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/> <tx:method name="resumeSubscription" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.Dat aAccessException, net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException"/>  <tx:method name="*" propagation="REQUIRED" rollback-for="net.rim.pushsdk.commons.PushSDKException, org.springframework.dao.DataAccessException"/> </tx:attributes></tx:advice>


• The default value for the subscribe, unsubscribe, suspendSubscription, and resumeSubscriptionmethods is net.rim.pushsdk.commons.PushSDKException,org.springframework.dao.DataAccessException,net.rim.pushsdk.subscription.cp.CPSubscriptionFailureException. This configures theBlackBerry® Push Service SDK to roll back a transaction when the subscribe, unsubscribe,suspendSubscription, or the resumeSubscription method throws the PushSDKException,DataAccessException, or the CPSubscriptionFailureException. PushSDKException andDataAccessException is thrown when the business logic in the SDK fails during the subscribe, unsubscribe, suspend,or resume events. The CPSubscriptionFailureException is thrown when your business logic, defined in theimplementation of the ContentProviderSubscriptionService interface, fails during the subscribe, unsubscribe,suspend, or resume events. For all other methods, the default value isnet.rim.pushsdk.commons.PushSDKException,


58

org.springframework.dao.DataAccessException. This configures the BlackBerry Push Service SDK to rollback a transaction when any of the other methods, except the <get*> or <find*> methods, throws thePushSDKException or DataAccessException.

aop:config<aop:config> <aop:pointcut id="subscriptionServiceOperation" expression="execution(* net.rim.pushsdk.subscription.SubscriptionServiceImpl.*(..))"/>

<aop:advisor advice-ref="subscriptionTxnAdvice" pointcut-ref="subscriptionServiceOperation"/>

</aop:config>

• You can change the default value of the expression attribute to specify the class you have created that implements theSubscriptionService interface. You can change the advice-ref attribute to specify the transactional advice foruse by the class.

• The default value "execution(* net.rim.pushsdk.subscription.SubscriptionServiceImpl.*(..))" configures the methods in the SubscriptionServiceImpl class to use the subscriptionTxnAdvicetransactional advice.

bean id="subscriptionService"<bean id="subscriptionService"class="net.rim.pushsdk.subscription.SubscriptionServiceImpl">

<property name="pushApplicationService" ref="pushApplicationService" />

<property name="subscriptionDAO" ref="subRDBMSDAO" /> <property name="httpClient" ref="httpClient" /> <property name="pushSDKProperties" ref="pushSDKProperties" /> <property name="contentProviderSubscriptionService" ref="contentProviderSubscriptionService" />

</bean>

• You can change the default value of the class attribute to specify the class you have created that implements theSubscriptionService interface.

• The default value net.rim.pushsdk.subscription.SubscriptionServiceImpl points to the defaultimplementation of the interface.

bean id="subRDBMSDAO"<bean id="subRDBMSDAO"class="net.rim.pushsdk.subscription.SubRDBMSDAOImpl">

<property name="dataSource" ref="dataSource"/> <property name="sqlProperties" ref="sqlProperties"/>


59

<property name="pushSDKProperties" ref="pushSDKProperties"/> <property name="cache" ref="subscriptionCache"/></bean>

• You can change the default value of the class attribute to specify the class you have created (for example, to use a relationaldatabase other than MySQL or Oracle, a flat file database, or an in-memory database) that implements theSubscriptionDAO interface.

• The default value net.rim.pushsdk.subscription.SubRDBMSDAOImpl points to the default implementation ofthe interface.

bean id="subscriptionRequestParser"<bean id="subscriptionRequestParser"class="net.rim.pushsdk.subscription.web.SubscriptionRequestParser">

</bean>

• You can change the default value of the class attribute to specify the class you have created that extends theSubscriptionRequestParser class to support additional HTTP request parameters for use in subscriberauthentication.

• The default value net.rim.pushsdk.subscription.web.SubscriptionRequestParser points to thedefault class that only supports the following properties for use in subscriber authentication: application ID, username,password, and subscription type.

bean id="contentProviderSubscriptionService"<bean id="contentProviderSubscriptionService"class="net.rim.pushsdk.subscription.cp.ContentProviderSubServiceImpl">

</bean>

• You can change the default value of the class attribute to specify the class you have created that implements theContentProviderSubscriptionService interface to take custom actions on subscribe, unsubscribe, suspend, andresume events.

• The default value net.rim.pushsdk.subscription.cp.ContentProviderSubServiceImpl points to thedefault implementation of the interface.

bean id="contentProviderAuthenticationService"<bean id="contentProviderAuthenticationService"class="net.rim.pushsdk.subscription.auth.ContentProviderAuthServiceImpl">

</bean>

• You need to change the default value of the class attribute to specify the class you have created that implements theContentProviderAuthenticationService interface if you are not using container-managed authentication.

• The default value net.rim.pushsdk.subscription.auth.ContentProviderAuthServiceImpl points tothe default implementation of the interface.

bean id="subscriptionCache"


60

<bean id="subscriptionCache"class="org.springframework.cache.ehcache.EhCacheFactoryBean">

<property name="cacheManager" ref="cacheManager"/> <property name="cacheName"> <value>net.rim.pushsdk.subscription.SubRDBMSDAOImpl</value> </property></bean>

• You can change the content within the value tags, the child element of <property name="cacheName">, if you wantto specify a different name for the cache. For example, you can set the name of the cache to the class you have created thatimplements the SubscriptionDAO interface. There is no requirements on the format of the name. It could be any arbitrarystring.

• The default cache name is net.rim.pushsdk.subscription.SubRDBMSDAOImpl.

Configure the properties for actions related to subscription and subscribersIf you use the setup application for the BlackBerry® Push Service SDK, you do not need to perform this task.




3. In the Subscription configuration properties section, change the values for the properties you like to modify.

Configuration properties for actions related to subscription and subscribers

You can modify configurations for actions related to subscription and subscribers in the PushSDK.properties file.


subscription.deregistration.url This property specifies the PPG address for deregistering subscribers in public

mode.

Default value is ${ppg.base.url}/mss/PD_cpDeregUser?pin=, where

${ppg.base.url} is a token to be replaced with an actual value.


deregistering subscribers is https://server:9000/mss/

PD_cpDeregUser?pin=.

subscription.suspend.url This property specifies the PPG address for suspending subscriptions in public

mode.


61



cpAction=suspend&pin=, where ${ppg.base.url} is a token to be



suspending subscribers is https://server:9000/mss/PD_cpSub?

cpAction=suspend&pin=.

subscription.resume.url This property specifies the PPG address for resuming subscriptions in public mode.


cpAction=resume&pin=, where ${ppg.base.url} is a token to be



resuming subscription is https://server:9000/mss/PD_cpSub?

cpAction=resume&pin=.

subscription.find.max.results This property specifies the maximum limit on the number of results that might be

returned by a subscriber find operation. A large value requires a large amount of

available memory.


subscription.validation.high.water.mar

k

This property specifies the maximum number of subscribers for validation that

determines which optimized query to use. Below this limit, a query optimized for a

small number of users is used. Above this limit, a query optimized for a large number

of users is used.


subscription.validation.batch.size This property specifies the maximum number of subscribers to load at once from

the database for validation. A large value requires a large amount of available

memory. A small value increases the number of calls to the persistent store.


subscription.matching.max.threads This property specifies the maximum number of threads to use for subscription

validation when the number of subscribers is above the limit specified in

subscription.validation.high.water.mark.

Default value is 5.


62

Configure the properties of the net.rim.pushsdk.commons.http.HttpClientImpl classIf you are using an HTTP client other than the one created using the HttpClientImpl class available from the BlackBerry®Push Service SDK, you do not need to perform this task.




3. In the HTTP client configuration properties section, change the values for the properties you like to modify.

Configuration properties of the net.rim.pushsdk.commons.http.HttpClientImpl class

You can modify the configurations for the net.rim.pushsdk.commons.http.HttpClientImpl class in thePushSDK.properties file.


http.connection.timeout This property specifies the duration of time (in milliseconds) allowed in attempting

to establish an HTTP connection to the PPG by an HTTPClientImpl object,

before a timeout error occurs and the connection attempt is terminated.

Default value is 60000, which is equivalent to 1 minute.


http.read.timeout This property specifies the maximum wait time (in milliseconds) allowed for data to

become available for reading from an HTTP connection to the PPG by an

HTTPClientImpl object, before a timeout error occurs and the read action is

terminated.

Default value is 120000, which is equivalent to 2 minutes.


http.is.persistent This property specifies (as a boolean) whether the HTTPClientImpl object uses

a persistent HTTP connection to connect to the PPG.

Default value istrue.

Setting this property to true or false might be influenced by performance

expectations of your application and available resources in your server and network

environment.


63

Configure the properties related to thenet.rim.pushframework.acknowledgement.AcknowledgementManager class




3. In the Acknowledgement configuration properties section, change the values for the properties you like to modify.

Configuration properties related to thenet.rim.pushframework.acknowledgement.AcknowledgementManager class

You can modify the configuration properties related to thenet.rim.pushframework.acknowledgement.AcknowledgementManager class in the PushSDK.properties file.


acknowledgement.manager.r

esult.notification.max.queue.s

ize

This property specifies the size of the internal memory work queue for storing of result

notifications arriving from the PPG. When the queue reaches the maximum size, as specified

through this property, the BlackBerry Push Service SDK starts rejecting the notifications and

the PPG retries to send them at a later time.


Note: If you set a value that is too small, result notifications sent by the PPG will be rejected

by the BlackBerry Push Service SDK and the PPG will retry sending the notifications up to 5

more times, with each retry attempt being delayed longer than the previous attempt. If you

set a value that is too large, the BlackBerry Push Service SDK might use up a lot of system

resources and increase the risk of information loss in the event of a system failure.

acknowledgement.manager.

max.threads

This property specifies the maximum number of AcknowledgementManager threads to

use for processing the result notifications from the internal memory work queue of result

notifications. When a thread is available, it goes to the queue to retrieve a batch of notifications

for processing.



64


Note: If you increase the number of threads and you have adequate system resources

available, it can improve the performance of processing result notifications. When adequate

system resources are not available, increasing the number of threads might degrade the

overall system performance.


atch.size

This property specifies the maximum number of result notifications that an

AcknowledgementManager thread reads as a batch from the internal memory queue of

result notifications and processes all the notifications in the batch at once. When a thread is

available but the total number of notifications in the queue is less than the maximum size of

a batch, as specified through this property, it does not read the batch right away. The thread

waits until the number of accumulated notifications in the queue adds up to the maximum

size of a batch, or waits for a period of time specified by the

acknowledgement.manager.batch.wait.time property, whichever occurs earlier, before it

continues the reading and processing.



atch.wait.time

This property specifies the period of time (in milliseconds) that an available

AcknowledgementManager thread waits when the total number of result notifications

in the internal memory queue of result notifications is less than the maximum size of a batch

specified in the acknowledgement.manager.batch.size property, before the thread continues

the reading and processing of notifications, unless the number of accumulated notifications

in the queue adds up to the maximum size of a batch before the specified waiting period is over.


Note: If result notifications are critical to the functioning of your Push Initiator, you might

choose a smaller value so that the notifications are processed faster.

Using the PAPNotify

If you are using the low-level API functionalities of the BlackBerry® Push Service SDK server-side library and want to handleacknowledgments (result notification messages and result notification response messages), you can use the PAPNotify webapplication template to deploy an implementation of the abstract servlet from the PAP component.

You can avoid having to create a web application by implementing the abstract servlet from the PAP component as well as theabstract method in the abstract servlet and registering the servlet with this web application. In your implementation of theabstract method, you can perform custom business logic for processing the acknowledgments.


65

System requirements and library dependencies: PAPNotify

Item Requirement




library dependencies • PAP and Commons components of the BlackBerry® Push Service SDK server-side

library

Configure the BlackBerry Push Service SDK to run in public or enterprise mode













66

Task Steps


mode.

























67













68





bean id="sqlProperties"<bean id="sqlProperties" class="net.rim.pushsdk.commons.SQLPropertiesImpl"> <property name="pushSDKProperties" ref="pushSDKProperties"/></bean>









69






<property name="configLocation"> <value>classpath:ehcache.xml</value> </property></bean>










70

Configure the properties related to the log file and loggingYou need to perform this task to specify the default location of the log file. Optionally you can perform this task if you want tochange the default values for the logging level, date format, and other properties related to the log file and logging. To developa Push Initiator that uses the BlackBerry Push Service SDK server-side library components, you need to configure the propertiesmanually by completing this task.






71

Glossary 6

APIapplication programming interface

HTTPHypertext Transfer Protocol

HTTPSHypertext Transfer Protocol over Secure Sockets Layer

IPPPInternet Protocol Proxy Protocol

PAPPush Access Protocol

PPGPush Proxy Gateway

Development Guide Glossary

72

Provide feedback 7

To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

Development Guide Provide feedback

73

http://www.blackberry.com/docsfeedback

Legal notice 8

©2010 Research In Motion Limited. All rights reserved. BlackBerry®, RIM®, Research In Motion®, SureType®, SurePress™ andrelated trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S.and countries around the world.

Apache Tomcat is a trademark of The Apache Software Foundation. Eclipse is a trademark of Eclipse Foundation, Inc. MySQL isa registered trademark of MySQL AB in the United States, the European Union and other countries. Java is a trademark of SunMicrosystems, Inc. All other trademarks are the property of their respective owners.

This documentation including all documentation incorporated by reference herein such as documentation provided or madeavailable at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition,endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in thisdocumentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation maydescribe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information thatis contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements,or other additions to this documentation to you in a timely manner or at all.

This documentation might contain references to third-party sources of information, hardware or software, products or servicesincluding components and content such as content protected by copyright and/or third-party web sites (collectively the "ThirdParty Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including,without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency,links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Servicesin this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way.

EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS,ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDINGWITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OFDURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALINGOR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCEOF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, AREHEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONSMAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENTPERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENTTHEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROMTHE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLEFOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCEDHEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY,INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES,

Development Guide Legal notice

74

http://www.blackberry.com/go/docs

FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OFBUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMSASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS,LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OFSUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARYLOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES.

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHEROBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITYFOR NEGLIGENCE OR STRICT LIABILITY.

THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THECAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE,TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHESOR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B)TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIMESERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIRRESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS.

IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE,AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITYARISING FROM OR RELATED TO THE DOCUMENTATION.

Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that yourairtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsingfunctionality with a subscription to the BlackBerry® Internet Service. Check with your service provider for availability, roamingarrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and servicesmay require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third partyrights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licensesare required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products andServices until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM'sproducts and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions,endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relationthereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separatelicenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or otheragreement with RIM.

Certain features outlined in this documentation require a minimum version of BlackBerry® Enterprise Server, BlackBerry® DesktopSoftware, and/or BlackBerry® Device Software.

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto.NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIESPROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION.

Research In Motion Limited295 Phillip Street


75

Waterloo, ON N2L 3W8Canada

Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom

Published in Canada


76

blackberry push service sdk development guide 925871 0316052041 001 1.0.0.5 us

Documents