Hack 97. Deploy BlackBerry Applications

Here are three ways to package your applications to be easily deployed on BlackBerry handhelds.

One of the most important things to consider when planning the deployment of a BlackBerry application is to determine how your customers will transfer the application onto their handheld devices. For best results, it is highly recommended that you offer your customers as many options as possible.

BlackBerry applications are developed in the Java Development Environment (JDE) [Hack #93] and produce a COD file. However, you need more than a COD file to successfully deploy the application to a handheld.

This hack will discuss how to package applications for deployment through the BlackBerry Desktop Manager, for over-the-air deployment, and to be pushed onto the device.

9.5.1. Deploy via the BlackBerry Desktop Manager

The BlackBerry Desktop Manager was the first method developed to deploy third-party applications onto BlackBerry handhelds. This method allows you to load applications from a desktop computer to a handheld through serial or USB cables, and it works well for all devices.

The BlackBerry 85x and 95x devices were C++ based and used an ALI file to load the required DLL files onto the handhelds. ALI files are not discussed in this hack because current model BlackBerry devices do not support them.

9.5.1.1. Create an ALX file.

For current model BlackBerry devices (5000, 6000, and 7000 series) the BlackBerry Desktop Manager expects an ALX file. The purpose of the ALX file is to describe the application and list the COD files that must be loaded onto the BlackBerry device. The COD files are highly optimized binary files that contain the Java bytecode class files of your application.

The easiest way to generate an ALX file for your application is by using the JDE. On the Project menu, click Generate ALX file. This will generate a default ALX file with the values that you set up in the Project Properties dialog. You may want to customize your ALX file manually, especially if you are using an automated build process such as Ant. The ALX file is basically an XML file. Here is an example of an ALX file for a third-party BlackBerry application:

 <loader version="1.0"> <application > <name > Idokorro Mobile Admin </name> <description > Mobile Admin allows remote network administration </description> <version>3.0</version> <vendor > Idokorro Mobile Inc. </vendor> <copyright > Copyright (c) 2005 Idokorro Mobile Inc. </copyright> <fileset Java="1.0"> <files > MobileAdminImages.cod MobileAdminUtil.cod MobileAdmin.cod </files> </fileset> </application> </loader> 

The id attribute of the <application> tag is a unique identifier used by the BlackBerry device to identify your application and to determine if the user is upgrading an existing application. On the BlackBerry handheld, users can view the ID or delete the application by selecting Options and then Applications. Pick a unique value that will not be confused with other available applications.

The <name> tag is the name of the application as it appears on the Home screen of a BlackBerry device.

The <description>, <vendor>, and <copyright> tags are used by the BlackBerry Desktop Manager to provide more information about an application.

The <version> tag allows you to specify the current version of your application. If you change this value after the application has been loaded onto a handheld, the Desktop Manager will recognize that an upgrade is available for the application. If you use a build script with a build system such as Ant, your script can automatically update the version number when creating new builds.

The <fileset> tags indicate the location of the actual COD files that the BlackBerry Desktop Manager will load. You can specify multiple COD files. It is also possible to specify attributes that will target different BlackBerry models. For more information about using these attributes, refer to the JDE documentation.

9.5.1.2. Package the application for download.

After the ALX file and the COD files have been generated, the application can be packaged for download. The simplest way is to compress the required ALX and COD files in a ZIP file and provide it as a downloadable file on your web site.

9.5.1.3. Load the application using the Desktop Manager.

To load a new application using the BlackBerry Desktop Manager, the user double-clicks the Application Loader icon. The Application Loader Wizard appears and displays all currently installed applications. The user clicks Add and then browses to the ALX file for your application (see Figure 9-6).

The most common problem that users experience when using the Application Loader Wizard is receiving the error message "No Additional Applications designed for your handheld were found."

Figure 9-6. BlackBerry Application Loader

The two most common causes are:

• The Application Loader cannot find the COD file(s) because the user only copied the ALX files to the PC.

• The BlackBerry Desktop Manager does not have a local copy of the handheld operating system installed that is compatible with the device currently connected to the PC.

The latter cause is easy to diagnose by checking to see whether the user's application list is empty. If so, the user must download the BlackBerry handheld operating system for her specific device from her carrier's web site.

9.5.2. Deploy Applications over the Air

The best and easiest way to deploy BlackBerry applications is via over-the-air (OTA) downloads. To install an application OTA, the user navigates to the location of the application files using the BlackBerry Browser, and then installs the application directly over the wireless network. The advantage of this installation method is that a connection to a desktop PC is not required, and the download and installation can be performed anywhere.

9.5.2.1. Create a JAD file.

OTA downloads require a file similar to the ALX file to identify and describe the application. A JAD file is used for this purpose. This file originates from the Java MIDP specification and is commonly used for J2ME application downloads for mobile phones. However, for BlackBerry applications, a few additional properties have been added to the JAD file format.

Here is an example of a JAD file for a BlackBerry application:

 Manifest-Version: 1.0 MicroEdition-Configuration: CLDC-1.0 MicroEdition-Profile: MIDP-1.0 MIDlet-Version: 3.0.1 MIDlet-Name: IdokorroMobileAdmin MIDlet-Jar-URL: IdokorroMobileAdmin.jar MIDlet-Jar-Size: 1 MIDlet-1: Idokorro Mobile Admin,img/mobileadmin.png,admin MIDlet-2: Idokorro Mobile Terminal,img/terminal.png,terminal MIDlet-Vendor: Idokorro Mobile Inc. RIM-COD-Module-Dependencies: net_rim_os,net_rim_ cldc,MobileAdminImages,MobileAdminUtil RIM-COD-URL-1: MobileAdminImages.cod RIM-COD-Module-Name-1: MobileAdminImages RIM-COD-Size-1: 66004 RIM-COD-URL-2: MobileAdminUtil.cod RIM-COD-Module-Name-2: MobileAdminUtil RIM-COD-Size-2: 39076 RIM-COD-URL-3: MobileAdmin.cod RIM-COD-Module-Name-3: MobileAdmin RIM-COD-Size-3: 92896 

The first three lines of the file indicate the minimum version of J2ME supported by the application. If your application is compatible with MIDP 1.0 and 2.0, use the lower version number.

Use the MIDlet-Version line to specify the version of your application. If you change this value, the user will be prompted to upgrade on subsequent downloads of the application.

Use the MIDlet-Name line to provide a unique name for your application. Be sure to choose a name that is unique and that will not be easily confused with other applications.

The MIDlet-Jar-URL and MIDlet-Jar-Size properties are not used by the BlackBerry device, but they must still be specified or the BlackBerry device will report the error "Invalid JAD File." In non-BlackBerry J2ME applications, OTA downloads are usually composed of a JAD file and a JAR file, which contain the Java CLASS files. These are irrelevant for BlackBerry downloads because the BlackBerry has its own special COD file format. If your application is not BlackBerry specific, you can still use a single JAR file, and the BlackBerry Enterprise Server (BES) will automatically convert the JAR file into a COD file when the user downloads the application files to a BlackBerry handheld.

The MIDlet-1 property is series of three comma-separated values (CSV). The first value is the name of the application as it appears on the Home screen of a BlackBerry device. The second value is the graphic file for the icon that will be displayed on the Home screen. The third value is for the arguments that will be passed to your public static void main(String[] args) method. Multiple application icons can be displayed simply by entering subsequent lines such as: MIDlet-2, MIDlet-3, etc.

Use the MIDlet-Vendor line to specify the company name that you want to display for your application.

Use the RIM-COD-Module-Dependencies line to specify what libraries your application depends on. For example, if it depends on the BlackBerry Browser module, the Phone module, or other third-party libraries, specify it here.

Use the RIM-COD-URL-1 line to specify the location of the COD file for your application. Use the RIM-COD-Module-Name-1 line to provide a unique name for the module. Use the RIM-COD-Size-1 line to indicate the COD file. If you have more than one COD file for the application, repeat these three lines for each COD file and increase the increment in the property name by one. For example: RIM-COD-URL-2, RIM-COD-Module-Name-2, RIM-COD-Size-2, etc.

9.5.2.2. Package the application for an OTA download.

When the JAD file is complete, you can post the JAD and COD files on your web server for download. Simply upload the files to your server using FTP or whatever mechanism you usually use to post web pages to your web site.

For OTA downloads to work properly, you must set the proper MIME types for the JAD and COD files on your web server. The MIME type for a COD file is application/vnd.rim.cod and the MIME type for a JAD file is text/vnd.sun.j2me.app-descriptor. For more information about how to configure MIME types, please refer to your web server documentation.

9.5.2.3. Download an application OTA.

To download your application from your web server OTA, users must simply point the BlackBerry Browser on their handheld to the URL of your JAD file. For example: http://www.idokorro.com/TelnetSSH.jad. Your users will then see something like the screen shown in Figure 9-7.

The user then clicks Download to transfer the application over the wireless network to the handheld. If the application has already been downloaded and a new version is available, the user will be asked if he wants to upgrade.

Figure 9-7. BlackBerry Browser OTA download

If you are going to post OTA downloads on your web server, it is highly recommended that you automatically redirect anyone using the BlackBerry Browser to your OTA download web page. To do this, configure your web server to redirect all User-Agents that contain the word "BlackBerry" to the OTA folder on your web server. This will save them the trouble of navigating through the rest of your site.

9.5.3. Push Applications

With the BES 4.0, it is now possible to wirelessly push applications to devices. This method is highly recommended for deploying an application to many handheld devices at once because it simplifies the installation and upgrade procedures.

To push an application to many BlackBerry devices at once, the receiving devices must be running Handheld System Software Version 4.0 or above, and have at least 16 MB of flash memory. Point the BES server to the ALX and COD files for the application, and select which users on your BES will receive the application. The BES can then install the files to the selected user devices and automatically push upgrades of the application to the handhelds whenever a new version is available. When the application is installed, users see a new icon on the Home screen of their BlackBerry handheld. For more information about this technique, see "Create a Simple Push Application" [Hack #90].

Paul Dumais