Developing for BlackBerry Devices

The BlackBerry platform of Research in Motion is quite popular for business applications. You can develop normal MIDlets as well as BlackBerry specific applications with J2ME Polish.

Preparations

For transforming and signing the JAR files to the BlackBerry proprietary COD format, you need to install either the BlackBerry Java Development Environment (JDE) or the BlackBerry Component Packages. The component packages are sufficient, though the JDE eases the debugging of your applications.

Please note that your should install the corresponding versions of the JDE/Component Packages for each BlackBerry handset version that you want to target. So if you are targeting 4.1, 4.2 and 4.3 BlackBerry devices, you need to install each of the corresponding JDEs. J2ME Polish will then select the appropriate JDE for converting a JAR file into a COD file. This is necessary since COD files generated with new JDE versions will not run on older platforms, and COD files generated with older JDE versions will not allow you (and J2ME Polish) to take advantage of features of later versions.

Download the JDEs or the Component Packages from http://www.blackberry.com/developers. On Unix systems these can be installed using an windows emulator like Wine. You can also install the Component Packages under Windows and then copy the installed directories to other operation systems.

After the installation you should define the blackberry.home in either ${polish.home}/global.properties, ${project.home}/${user.name}.properties or in your build.xml script. blackberry.home should point to the directory that contains all JDEs or Component Packages. By default this points to "C:/Program Files/Research In Motion". In your build.xml script the definitition could look like this:

<property 
	name="blackberry.home" 
	location="C:/Program Files/Research In Motion" 
/>

Sample JDE Installation Structure

If you work in a team, it is a good idea to install the Component Packages into a shared project. In this way you can use one installation setup for several projects and teams easily. It also eases the sharing of signing certificates considerably (see below). For our projects we do have installed all Component Packages into the "blackberry" project with following directory structure:

blackberry                           (root directory)
blackberry/blackberry.properties     (signing properties)
blackberry/certificate               (certificate directory)
blackberry/certificate/sigtool.csk   (private key)
blackberry/certificate/sigtool.db    (signing services)
blackberry/certificate/client-RBB-XXXX.csi (certificate)
blackberry/certificate/client-RCR-XXXX.csi (certificate)
blackberry/certificate/client-RRT-XXXX.csi (certificate)
blackberry/BlackBerry JDE Component Package 4.1.0 (for 4.1 devices)
blackberry/BlackBerry JDE Component Package 4.2.0 (for 4.2 devices)
blackberry/BlackBerry JDE Component Package 4.3.0 (for 4.3 devices)

In project's we then use following property definitions in the build.xml scripts for BlackBerry support:

<project basedir="." default="j2mepolish" name="myproject">
	<property file="${user.name}.properties" />
	<property name="polish.home" location="C:\Program Files\J2ME-Polish" />
	<property file="${polish.home}/global.properties" />
	<property name="blackberry.home" location="../blackberry" />
	<property file="${blackberry.home}/blackberry.properties" />

The above property structure allows you to use user-specific settings in case you cannot deal with the general team-settings, while easing the life of all team members considerably. You can change blackberry.home for example by specifying it in ${project.home}/${user.name}/properties, e.g. when your login name is "dave", you can define it in ${project.home}/dave.properties like this:

blackberry.home=E:\\dev\\Research in Motion

You can also define the variable blackberry.emulator.home in case you want to use different JDEs for building and for simulating. This is handy if you have the certification keys in one place and fullblown JDEs in a different place.

blackberry.emulator.home=E:\\dev\\Research in Motion

Converting JARs into CODs

When you target BlackBerry devices like the BlackBerry/8100 device and have set the blackberry.home property, J2ME Polish will automatically invoke the rapc compiler for converting the JAR file into a COD file in the finalize step of the build process. Remember that resources should be less than 64 kb in size for older BlackBerry platforms, otherwise the rapc process will abort the processing.

Signing COD Files

J2ME Polish can also automate the requesting of signatures during the build process.

Obtaining and Installing Certificates

Signatures are required for accessing some Blackberry specific security sensitive APIs and require a certificate that can be obtained at https://www.blackberry.com/SignedKeys. After signing up with BlackBerry you will receive 3 certificates, for example:

client-RBB-34343989.csi
client-RCR-34343989.csi
client-RRT-34343989.csi

Each certificate is responsible for specific API usages, usually the RRT (secure runtime API access) is the most important. You now need to register the certificates by following the installation instructions - usually double clicking the certificate does the trick. After the installation you will obtain the two text files sigtool.csk and sigtool.db that will be stored in ${jde.home}/bin.

Automating the Application Signing

In your Ant build.xml script, ${polish.home}/global.properties or ${project.home}/${user.name}.properties you then need to define the blackberry.certificate.dir property, e.g.:

<property name="blackberry.certificate.dir" location="${blackberry.home}/certificates"/>

In case the sigtool.csk and sigtool.db files are not included in the same location like the certificates, you also need to define the blackberry.sigtool.dir property:

<property name="blackberry.sigtool.dir" location="${blackberry.home}/sigtool"/>

When you specify the password as well, J2ME Polish uses this for requesting the signatures without manual intervention. For such cases the password needs to contain only ASCII characters, otherwise J2ME Polish can't include the password automatically.

<property name="blackberry.certificate.password" value="secret"/>

Note that BlackBerry only provides a GUI based tool for JDEs before 2.0.1. For successfully signing your application automatically you need to run the build process in the foreground, so that the J2ME Polish can send key events to the foreground window of the BlackBerry SigTool during the build with such JDEs.

Note also that the blackberry SigTool application does not work on Unix systems. This shlashdev guide describes how to run the SigTool on Unix.

Debugging

An blackberry project file (.jdp) gets created automatically with every blackberry build. You can debug by building and running the project in the BlackBerry JDE with the project file imported.

Verification error

It may happen that a blackberry build can't be executed due to a verification error. The device will respond to the execution of the application with something like this :

Error starting appname: Module 'appname' has verification error XXXX at offset XXXX

There are numerous reasons for this behaviour:

The signing went wrong. Please check the signing of the application.
A derived or subclass of another class tries to access a static variable directly. Create a get() method for this variable to access it.
Remove unused imports
Remove System.out.println() calls
Make sure every method has a valid qualifier like private/public/protected

To identify the class and method which causes the error, you can do the following :

Open the emulator of the BlackBerry JDE
Load the application
Open the application
An error screen should appear stating something like this :
```
jvm error 104 uncaught runtime exception
```
Choose from the underlying menu (using the arrow keys) the option "catfail"
Now choose the right most point to save a file named "failure.zip" to your disk
Extract the files within failure.zip to your disk and open the .bug file

There are three interesting values in the .bug file:

VM:VECPs

(the package)

VM:VECCs

(the class)

VM:VECMm

(and the method which causes the error)

Using the J2ME Polish GUI on BlackBerry Devices

The J2ME Polish GUI can be used normally on BlackBerry devices as well. In order to make most of the system, J2ME Polish converts your MIDlet into a native BlackBerry UiApplication. This allows J2ME Polish to process trackwheel/trackball events and so on correctly. The successful conversion requires that your MIDlet uses a public constructor.

BlackBerry TextFields

On BlackBerry devices native BlackBerry EditFields are used for text input. These native fields work in the same way like in other BlackBerry applications, but they do not offer the same wealth of design options like J2ME Polish TextFields.
Therefore, J2ME Polish displays normal TextFields that you can fully design when the field is not focused. When the TextField is focused, however, we switch to the native BlackBerry EditFields. You can still specify the background, border and font styles of a focused TextField, but advanced designs like text effects will not be supported.

BlackBerry DateFields

Similar to TextFields, J2ME Polish uses native BlackBerry DateFields when a J2ME Polish DateField is focused. This is why the visualization of the DateField might change when it is focused.

Platform Requests in J2ME Polish Applications

For enabling platform requests using the MIDlet.platformRequest(String url) call, you need to specify the preprocessing variable polish.BlackBerry.enablePlatformRequest in your build.xml script:

<variable name="polish.BlackBerry.enablePlatformRequest" value="true" />

Note that this functionality requires a signed application.

Developing Native BlackBerry Applications

You can also develop native BlackBerry applications by defining the blackberry.main variable that contains the name of the class that extends net.rim.device.api.system.Application.

<variable name="blackberry.main" value="com.company.product.ProductApplication" />

Please note that the currently provided BlackBerry library does not contain all available classes, compare the following Troubleshooting section.

Deploying a BlackBerry Application Over The Air

The BlackBerry platform supports delivery of applications over the air (OTA). These are the steps to get this kind of provisioning to work:

Create a .cod file
Unpack the .cod file. The 'outer' .cod file is a .zip file in disguise and you can unpack it with every unzip program available. Beware that the outer .cod file contains inner .cod files and that one inner .cod file has the same name as the outer .cod file. It is imperative that every inner .cod file is extracted, even if you need to overwrite the outer .cod file in the process.
While building for a BlackBerry device, the created JAD file contains modified URL safe entries. In case you require the original JAD file, use the .jad.bak one. The original .jad file which is generated from the rapc compiler contains entries of the form RIM-COD-URL-1: BlackBerry$2d8100$2den_US$2dblank-1.cod. Note the sequence "$2d". This should encode the charater "-" but the webserver will need the sequence "%2d" to find the correct file. The file .jad.alt.jad contains corrected entries.
Make all inner .cod files and the corrected .jad file available on a web server. The mimetype for the .cod file should be application/vnd.rim.cod and for the .jad file text/vnd.sun.j2me.app-descriptor.

Useful Virtual Devices

The J2ME Polish device database contains several virtual devices that you can target for limiting the number of BlackBerry builds. Instead of building for BlackBerry/8100 and BlackBerry/8800 for example, you can generate one build for the virtual BlackBerry/4.2 device. Note, however, that these virtual devices do not contain a screen size definition, so if you have resources that depend on the screen resolution, you should target real devices instead.
Following virtual devices are available:

BlackBerry/4.1: for devices like the 8700, 7290 etc
BlackBerry/4.2: for devices like the 8100, 8800 etc
BlackBerry/4.3: for devices like the 8120, 8130 etc

Troubleshooting

Deactivate Obfuscation

You should deactivate obfuscation for BlackBerry devices, since the rapc compiler already removes any unneeded fields, classes etc. Also you can get verification errors on the BlackBerry devices when you enable the obfuscation. You can skip the obfuscation for test builds as well as for BlackBerry devices with this definition in your build.xml script:

<obfuscator name="ProGuard" unless="test || polish.blackberry" />

Rewriting JAD Properties

The BlackBerry tools do embedd application/JAD properties into the application during the build process. During OTA installation over the air, any rewritten or appended JAD properties will be ignored. You can consider building or converting the application upon request for personalizing it.

Phone Calls with DTMF

When using the J2ME Polish UI, you can send DTMF tones after initiating a phonecall by separating the MSISDN and the DTMF part with a backslash or a 'p':

	myMidlet.platform.request("tel:001232878/88779");
	myMidlet.platform.request("tel:001232878p88779");

Platform Requests

<variable name="polish.BlackBerry.enablePlatformRequest" value="true" />

Note that this functionality requires a signed application.

0/Space Is Mapped To Fire

By default the '0' and 'space' key will be mapped to a 'FIRE' game action on BlackBerry devices. This will allow your users to select entries and trigger OK commands with 0/space. You can deactivate this behavior by specifying the preprocessing variable polish.BlackBerry.mapSpaceToFire:

<variable name="polish.BlackBerry.mapSpaceToFire" value="false" />

Using Native High Level LCDUI Components

Normally you can mix native highlevel LCDUI components like javax.microedition.lcdui.TextBox with J2ME Polish in your application by using fully qualified class names. This is not supported on BlackBerry devices, because the native BlackBerry user interface API is used by J2ME Polish. On BlackBerry devices you cannot mix LCDUI components with BlackBerry user interface components in the same application. Therefore you either either must not fully qualify native LCDUI components in your application or you need to deactive the J2ME Polish UI for BlackBerry.
Please note: In most cases you use a native TextBox so that the user can edit long texts - since J2ME Polish uses native EditFields on BlackBerry when a TextField is focused, there is no benefit in using a native TextBox anyhow.

<variable name="polish.BlackBerry.mapSpaceToFire" value="false" />

Username:
Password: