J2ME Polish
J2ME Polish 2.4 Documentation
Enough Software

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 definition 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.5.0 (for 4.5 devices)
blackberry/BlackBerry JDE Component Package 4.6.0 (for 4.6 devices)
blackberry/BlackBerry JDE Component Package 4.7.0 (for 4.7 devices)
blackberry/BlackBerry JDE Component Package 5.0.0 (for 5.0 devices)
blackberry/BlackBerry JDE Component Package 6.0.0 (for 6.0 devices)
blackberry/BlackBerry JDE Component Package 7.0.0 (for 7.0 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.

If rapc fails because there is not enough heapspace, you can specify the preprocessing variable or Ant property blackberry.rapc.opts, e.g.:
<property name="blackberry.rapc.opts" value="-Xmx512m"/>
This example will set the maximum usable heapspace to 512 MB, which is actually the default setting.

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:

  1. client-RBB-34343989.csi
  2. client-RCR-34343989.csi
  3. 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 this generated project file. You will find the file in the build/BlackBerry/${device}/{language}/ folder.
To import a project right-click on the workspace in the files view of the JDE and select "Add Project...".

In case you use binary libraries in your project, J2ME Polish will generate two projects - one library project and another CLDC application project that depends on the generated library project. You will need to add both projects to the JDE - the library project will be called like your application with an additional "LIB" at the end.

When you are using the serialization or RMI features of J2ME Polish, you should not rely on de.enough.polish.io.Serializable but instead implement de.enough.polish.io.Externalizable when using running projects from within the JDE. This is required since Serializable classes are processed within the class files in byte code, but in the JDE only the source code is used.

Using the J2ME Polish UI on BlackBerry Devices

The J2ME Polish UI 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.

BlackBerry Menubar

J2ME Polish uses the fullscreen attribute of the <build> element of the <j2mepolish> task to determine whether commands should be rendered by J2ME Polish or natively by BlackBerry. We recommend to use native command rendering on BlackBerry which is achieved with one of the following settings:

<build fullscreen="false" ...>

or use the <variables> section:

<variable
  name="polish.FullScreen"
  value="false" if="polish.blackberry || polish.android" />

or

<variable name="polish.FullScreen" value="menu" unless="polish.android || polish.blackberry" />

You can also add separators to the native menu by adding a Command.SEPARATOR command (the style is only used for other platforms):

import de.enough.polish.ui.Command;
[...]
	
	//#style menuSeparator
	Command cmdSeparator = new Command("", Command.SEPARATOR, 5 );
	myScreen.addCommand( cmdSeparator );

BlackBerry Alerts

You can instruct J2ME Polish so that it uses native BlackBerry alerts instead of ones rendered by J2ME Polish. This improves the integration into the BlackBerry platform and is a recommended setting in your build.xml script:

<variable
  name="polish.useNativeAlerts"
  value="true" if="polish.blackberry || polish.android" />

Using Native BlackBerry Fields in a J2ME Polish App

You can also include any native Blackberry fields directly in J2ME Polish screens by using the de.enough.polish.blackberry.ui.FieldItem. This item accepts any net.rim.device.api.ui.Field in it's constructor:

//#if polish.blackberry
	import net.rim.device.api.ui.component.CheckboxField;
	import de.enough.polish.blackberry.ui.FieldItem;
//#endif

[...]

//#style screenWithNativeFields
Form form = new Form("Native Fields");
//#style text
form.append("Here is a native CheckBoxField:");
CheckBoxField checkField = new CheckBoxField("Show again", true);
//#style nativeField
FieldItem fieldItem = new FieldItem( checkField );
form.append( fieldItem );

Native CheckBoxField

Platform Requests in J2ME Polish Applications

For enabling platform requests just sign your application. In the emulator you can also use the MIDlet.platformRequest(String url) call when you specify the preprocessing variable polish.BlackBerry.enablePlatformRequest in your build.xml script:

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

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" />

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.2TrackBall 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/7.1: for OS 7.1 devices
  • BlackBerry/7.0: for OS 7.0 devices
  • BlackBerry/6.0: for OS 6.0 devices
  • BlackBerry/5.0: for OS 5.0 devices
  • BlackBerry/4.7: for OS 4.7 devices (like the BlackBerry/Storm)
  • BlackBerry/4.6: for OS 4.6 devices like the BlackBerry Bold
  • BlackBerry/4.5: for OS 4.5 devices like the BlackBerry Curve
  • BlackBerry/4.3: for devices like the 8120, 8130 etc
  • BlackBerry/4.2TrackBall: for 4.2 devices with trackball like the 8100, 8800 etc
  • BlackBerry/4.2: for 4.2 devices without trackball
  • BlackBerry/4.1: for devices like the 8700, 7290 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

For enabling platform requests using the MIDlet.platformRequest(String url) call, you need to sign your app or 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 on real devices.

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" />

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 behavior:

  • 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 :

  1. Open the emulator of the BlackBerry JDE
  2. Load the application
  3. Open the application
  4. An error screen should appear stating something like this : jvm error 104 uncaught runtime exception
  5. Choose from the underlying menu (using the arrow keys) the option "catfail"
  6. Now choose the right most point to save a file named "failure.zip" to your disk
  7. 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)

back to top