Hack 90. Create a Simple Push Application

You don't have to be able to write J2ME code to create a useful BlackBerry application. The BlackBerry Browser along with MDS allows you to push data to devices.

As ubiquitous as Java is now, not every programmer is in love with the language. But since the BlackBerry is a J2ME-based device, if you want to create a corporate based application, you have to use Java, right? Actually, no. RIM provides excellent hooks into the BlackBerry Browser so that when used in conjunction with a BES, you can create much of the same functionality of a full-blown J2ME application in any language that can use HTTP. You can create applications that push web content to certain devices so that it is there without the user having to pull the content by visiting the page in the BlackBerry Browser. The content that is pushed is cached on the device, making it available whether the user is in a wireless coverage area or not. The Mobile Data Service provides flexibility in how you notify the user that new content has been pushed to the device.

This hack will show you how to create a simple push application to give you a jumpstart in the world of MDS Push. You can even test this using the BlackBerry Simulator [Hack #93].

For this to be a viable solution, your target audience must have devices homed on your BES infrastructure.

8.7.1. Enable the MDS Push Feature

By default, the Mobile Data Server is not enabled for push applications. You'll need to enable it and restart the MDS service to turn it on. In BlackBerry Manager, right-click on the server that you'd like to enable and select the "Set as Mobile Data Service Push Server" option. Once enabled, a checkmark appears before the option, as shown in Figure 8-8.

Figure 8-8. Enabling the push server

8.7.2. Design Your Push Application

You'll need a couple pieces of data to send content to a device. Here is a list of the minimum:

Name of MDS push-enabled BES
Port of MDS web server (default is 8080)
Either the PIN or email of the recipient

Once you enable the MDS Push Server, a version of Apache Tomcat is made available on the BES to accept HTTP requests from your application. To push content to a device, you'll need to use an HTTP POST to a specific URL on your MDS server. You'll specify the device information in the URL parameters. There are several ways to customize the behavior of your push application through the use of custom HTTP headers in the request. Table 8-1 shows a list of the headers that are available and what functionality they provide.

Table 8-1. Custom HTTP headers for MDS Push applications
Header name	Description
`X-RIM-Push-Type`	Values can be `Browser-Message, Browser-Content`, or `Browser-Channel` (see description later in this hack).
`X-RIM-Push-Title`	Display name of your application. Displayed in the Home screen or message subject depending on value of `X-RIM-Push-Type`.
`X-RIM-Push-Channel-ID`	String that identifies your application.
`Content-Location`	The URL for the content you are sending.
`X-RIM-Push-UnRead-Icon-URL`	A URL for an image to display on the Home screen when your application has sent data that has not yet been read by the user.
`X-RIM-Push-Read-Icon-URL`	A URL for an image to display on the Home screen when your application has no new content on the device.
`X-RIM-Push-Priority`	Value can be `none` (default), `low, medium`, or `high`, each with increasing levels of intrusiveness to the user.
`X-RIM-Push-Ribbon-Position`	Specifies where your application icon appears in relation to the other icons on the Home screen.
`X-RIM-Push-Description`	A brief description of your application.
`X-RIM-Push-Deliver-Before`	Specifies a date that the content must be delivered by. If it is not sent by the specified date, MDS will not push the data.
`X-RIM-Push-ID`	Specifies a unique message ID that can be used to cancel or check status of delivery.
`Content-Type`	Defines the MIME types included in the pushed content.
`Cache-Control`	Value can be `no-cache, max-age`, or `must-revalidate`.
`X-RIM-Transcode-Content`	Specifies which type of content the server should transcode (convert from one digital format to another).
`X-RIM-Push-Reliability`	Specifies the delivery reliability mode of the content. Value can be `TRansport, Application`, or `Application-Preferred`.
`X-RIM-Push-NotifyURL`	Specifies a URL for the MDS server to send a result notification.

8.7.3. Push Type

The X-RIM-Push-Type header determines the location and appearance of the application on the BlackBerry. There are three types of pushes you can make to the device:

Browser-Channel: Creates an icon on the Home screen. You can create custom icons that display when your application contains read or unread data. See Figure 8-9.
Browser-Message: New content shows up in the message list with a special icon that differentiates it from regular messages. See Figure 8-10.
Browser-Content: Sends content to device where it's stored in the browser cache. There is no icon that represents new content.

Figure 8-9. Browser-Channel push app on Home screen

Figure 8-10. Browser-Message push app in message list

8.7.4. The Code

 use strict; use LWP::UserAgent; use HTTP::Request; my $MDS = "localhost"; my $PORT = "8080"; my $PIN = '2100000A'; my $url = "http://del.icio.us/html/davemabe/?tags=no&count=20"; my %headers_to_send = (      'Content-Location'  => $url,  'Content-Type'  => "text/html",  'X-RIM-Push-Title'  => "Dave's del.icio.us Bookmarks",  'X-RIM-Push-Type'  => "Browser-Channel",  'X-RIM-Push-Channel-ID' => "daves-delicious",     ); my $browser = LWP::UserAgent->new; my $get_response = $browser->get($url);  my $content = $get_response->content; my $mds_url =        "http://$MDS:$PORT/push?DESTINATION=$PIN&PORT=7874&REQUESTURI=/";     my $request = HTTP::Request->new;      $request->method('GET');  $request->uri($mds_url); foreach my $header (keys %headers_to_send) {        my $value = $headers_to_send{$header};    $request->header($header,$value);     } $request->content($content); my $response = $browser->request($request); if ($response->is_success) {       print "Push was successful.  Sent to $PIN.\n";     } else {       print "There was a problem.  Code was: ",$response->code,"\n";     }

8.7.5. Run the Code

Type the code into your favorite text editor and save the file as mdspush.pl. Bring up a command prompt and type the following in the directory where you saved the file.

 C:>perl mdspush.pl

8.7.6. Output

You'll get different output from this command depending on whether your push was successful or not. If the push was successful, you will get the following output:

 Push was successful. Sent to 2100000A.

If there was a problem with the request, you will get an error message along with the HTTP response code that MDS returned:

 There was a problem. Code was: 500

In the event the code is unsuccessful, there are some common errors that should be checked. In my testing, I created some errors and got these status codes. An HTTP response code of 500 was given when I used an incorrect URL for my MDS. A response code of 403 indicated I had either sent to the wrong PIN, or the URL for the content I was sending to the device was invalid.

When your code is successful, you should get an icon on the device's Home screen, as shown in Figure 8-9, and when you click on the icon, you should see a list of links I've recently posted on my del.icio.us page, as shown in Figure 8-11.

Figure 8-11. The pushed content on the device

As well as placing an icon on the Home screen, a browser channel push will add an additional folder underneath your BlackBerry Browser's bookmarks that contains all channel applications on the device. The user can use the trackwheel to open, view details, reorder, or delete the channels you push.