Mobile platforms - Blackberry

After having gone thru the Android documentation and videos from Google IO, I found the documentation on Blackberry to be somewhat disorganized – it is not easy to get the big picture and grasp key concepts. You need to go thru a lot of documentation to figure out how things works together as a system. I also tried to access the materials from http://www.blackberrydevcon.com/2010-on-demand but it turned out that it would require a registration for $ 20. That was a bit of a WTF moment … I mean, you want to make money by selling conference materials? Who does that?? Anyway I proceeded to register on https://www.eventreg.com/pls/pg_rim/reg_rim.reg_login?icpid=&ipr_code=ONDNON and after filling two lengthy forms, was unable to make a payment despite getting a registration id. I wrote to BlackBerryDEVCON@eventreg.comwith my registration id (this was on 3rd Mar), but am yet to hear from them. Rather discourgaing for somene starting off on a new platform.

The Blackberry Platform

The Blackberry platform consists of the following key components:

• Phone: Blackberry phones support two kind of applications:
  • Java Apps: These are native Blackberry apps which can take full advantages of all the features available in a Blackberry phone, for example the BBM API.
  • WebWorks Apps: Browser based apps built using HTML, CSS, JS and capable of accessing native APIs thru the WebWorks SDK.
• Tablet: One can build playbook tablet applications in two ways:
  • Adobe AIR apps: Based on Action Script 3 with a bunch of Blackberry specific APIs. Use this to build apps with a native look and feel.
  • WebWorks apps: Similar to WebWorks apps for the Blackberry phone.
• Platform Services: Bunch of services provided by RIM including Push, Location,Advertising and Payment services
• Connectivity Services: RIM also provides a couple of connectivity services:
  • Blackberry Enterprise Server (BES): Enterprises can make their mail infrastructure available over the Blackberry network using BES which acts as a relay between the mail server and Blackberry’s NOC co-located with a carrier providing Blackberry services. One of the components of BES called the Mobile Data System (MDS) provides  HTTP and TCP proxies for a Blackberry application. This allows a Blackberry device to communicate with app / web-servers behind a corporate firewall without using VPN.
  • Blackberry Internet Services (BIS): For individuals, the alternative to BES is the BIS. This provides the ability to access mail over POP and IMAP email without going thru BES. The service is provided in partnership with a carrier.
• AppWorld: The blackberry application store front, similar to the iPhone App Store

This post is specific to Java development for the Blackberry phones. Moreover, it is specific to Blackberry 5 since 75-85% of app downloads from the App World are from Blackberry 5 devices.

Java ME

Native apps on the Blackberry phone are Java apps that run on RIM’s JVM implementation. This Java API is based on Java ME with Blackberry adding its own extensions. If you are new to Java ME like I am, here is a quick review:

Java ME (Micro Edition) is Java targeted for small devices. It is a collection of specs and technologies to address the needs of providing a programming interface to small devices. Since there is a large variety in the types of devices and their capabilities, it is quite likely that a device manufacturer would implement some specs and not others, leading to API fragmentation and hence non-portable code. To address this, Java ME defines capabilities for devices which are organized into Configurations, Profiles and Optional APIs:

(Organization of the Java ME technologies – source:http://developers.sun.com/mobility/getstart/articles/survey/)

• Configurations: A configuration is a specification for a virtual machine + some base APIs designed for a specific kind of device, based on memory constraints and processor power.
  • Connected Limited  Device Configuration (CLDC): The CLDC is meant for small wireless devices with intermittent network connections, like pagers, mobile phones and PDAs
  • Connected Device Configuration (CDC):  The CDC is a superset of the CLDC meant for larger devices with robust connections, like Set-top boxes and internet appliances.
• Profiles: A profile is more specific than a configuration. A profile is based on a configuration and adds APIs for UI, Storage, or whatever else is required to develop apps. For CLDC, a profile called Mobile Information Device Profile (MIDP) is specified. For CDC, there is a hierarchy of profiles:
  • Foundation Profile
  • Personal Basis Profile
  • Personal Profile
  • Information Module Profile
• Optional APIs: A device implementing Java ME may define additional optional APIs besides the ones that are defined as a part of a Java ME profile.

Based on the configurations, profiles and optional APIs, Java ME is able to address a wide variety of small devices including Handsets, Smart-cards and embedded devices:

(Map of the Java ME Universe – source:http://developers.sun.com/mobility/getstart/articles/survey/)

A device implements a stack consisting of a Configuration, Profile and Optional APIs. For wireless devices like mobile phones, the stack is based on CLDC, MIDP and some optional APIs. An application targeting the MIDP profile is called a MIDlet.

(Stack for wireless devices. Source:http://www.oracle.com/technetwork/java/javame/tech/technology-139316.html)

As one can imagine, despite the CLDC and MIDP being defined, a lot of commonly required functionality and the way it is provided remains un-defined, thus introducing scope for API fragmentation and un-portable code. This was addressed thru JSR 185 – Java Technology for the Wireless Industry – a specification that addresses fragmentation by defining key APIs and code portability issues by clarifying spces and providing a suite of compliance tests. JSR 185 consists of CLDC 1.0 or 1.1, MIDP 2.0 and WMA (Windows Messaging API – JSR 120 and JSR 205), with support for MMAPI (Mobile Media API – JSR 135) being optional:

(JSR 185 – JTWI Stack. Source: http://developers.sun.com/mobility/getstart/)

This was superseded by the MSA (Mobile Services Architecture) specification which defined two stacks: a full stack of 16 JSRs and a subset of 8 JSRs:

(MSA Stacks. Source: http://developers.sun.com/mobility/midp/articles/msaintro/)

Blackberry 5 is based on CLDC 1.1, MIDP 2.0 and is JSR-185 compliant. It also supports the full MSA stack except for JSR 184 (3-D graphics), JSR 180 (SIP) and JSR 229 (Payment). For other JSRs supported by Blackberry 5, seehttp://docs.blackberry.com/en/developers/deliverables/9095/Support_for_standard_Java_APIs_446981_11.jsp

Blackberry Applications

Blackberry applications are of two types:

• MIDlet Application: A MIDlet is an application targeting MIDP (javax.microedition namespace). Such an app can run on other MIDP 2.0 compliant phones from other vendors
• Blackberry Java Application: A Blackberry Java Application (also called a RIMlet) targets the CLDC, but uses Blackberry specific APIs (from the net.rim namespace). Such an app can run only on a Blackberry device.

Unless your code is targeting mulitple Java ME platforms, it makes sense to build Blackberry Java applications since they tend to be a lot richer than MIDlets. Specifically, if you want the look and feel of applications that RIM ships with a Blackberry (also called “native apps”), then you should build a Blackberry Java application by usingnet.rim.device.api.ui and not use javax.microedition.lcdui. More differences on the UI capabilities of both frameworks are given onhttp://www.blackberry.com/developers/docs/5.0.0api/UI-summary.html.

Note that all APIs are always available to all apps. So if your app is using the Blackberry UI, you can always invoke MIDP APIs. If your app is using the MIDP UI, you can always invoke Blackberry APIs, but of course doing so would render the application non-portable. The only exception to this is on mixing UI. The MIDP UI model allows concurrent access while the Blackberry UI model does not and hence mixing UI library calls is unsupported.

In the rest of this post, I would be focussing mostly on the Blackberry Java Application.

Startup

A Blackberry application can start in one of the following ways:

1. Use clicking an icon on the Home screen
2. By another app
3. OS starting an app automatically when the device starts
4. OS starting an app at a scheduled time

This startup is managed by an entity called the Application Manager. An running application can obtain a reference to the Application Manager by callinggetApplicationManager(), and then, can use this to:

• Run or Launch another application
• Schedule an application to run at a specific time
• Post a global event to the OS
• Lock and Unlock the system

To start an application, the App Manager creates a new process and a thread within that process and then starts the main() function on that thread with a set of input parameters. The parameters are specified in the application descriptor. It is possible to create multiple descriptors for the same app and associate them with different icons on the screen, This allows the creation of multiple entry points for the same app.

Event Processing

Once started, an application can choose to do a series of operations and then quit, never showing a UI. However, most applications want to stay around and respond to system events, including UI events. For this, one of the threads of the application needs to acquire what is called the Event Lock by calling Application.getEventLock(). Only one thread in the application can acquire this lock – this thread is then called the Event Thread. Typically, the first thread acquires this lock by calling enterEventDispatcher(). Once this method is called, the application starts receiving system events. Note that this does not mean that the application is showing a UI – just that is it receiving all system events, including UI events. So as of now, the application is still running in the background. An application can control whether it wants to continue processing systems events by toggling setAcceptEvents().

Showing a UI

All the visible elements in a Blackberry Java Application are of three types:

• Fields: A building block element that is used to work with a particular kind of data for which it draws the UI and if required handles user-input. It typically corresponds to a control like a button / text-field, etc. You can create custom Fields by sub-classing the Field class, implementing the layout() and paint()abstract methods and optionally overriding getPreferredHeight() andgetPreferredWidth() methods.
• Managers: Responsible for arranging fields. Each field must belong to only one manager. Since a manager is also a field, managers are composable, making it possible to build complex, rich, UI layouts. There are several types of managers provided: Horizontal, Vertical, Grid, Flow, Absolute, etc., and you can also build your own by sub-classing the Manager class and implementing sublayout(),getPreferredHeight() and getPreferredWidth() methods and optionally overridingsubpaint() method.
• Screens: A screen is a window that is active at any given time. There are two types of screens: PopupScreen and a FullScreen.

(Blackberry UI Framework. Source:http://www.blackberry.com/developers/docs/5.0.0api/UI-summary.html)

The way the system works is that the UI Engine maintains a stack of Screen objects. As new screens are created, they are pushed on the display stack. Only the screen at the top receives input events. When a screen is popped from the stack, the underlying screens are drawn as necessary. Note that the Blackberry display stack is not the same as the Android back-stack. The Android back-stack is a system-managed structure, scoped to a task with acitivities from different processes getting interleaved. The Blackberry display stack is a per-process application-managed stack of Screens.

To show a UI, the application extends the net.rim.device.api.ui.UiApplication class (which implements UiEngine and extends the Application class), creates an instance ofMainScreen (which is of type FullScreen) and then pushes this instance on the display stack.

class MyApp extends UiApplication {
 MyApp() {
  MyAppScreen myAppScreen = new MyAppScreen();
  pushScreen(myAppScreen);
 }

 public static void main(String[] args) {
  MyApp app = new MyApp();
  app.enterEventDispatcher();
 }
}

class MyAppScreen extends MainScreen {
 MyAppScreen() {
  // add fields etc.
 }
}

Termination

An application terminates when System.exit() is called. This method causes the Blackberry JVM to terminate the process of the caller. For applications that show a UI, the typical way of quitting is that when the close() method is called on a screen, it pops the screen from the display stack, and if the display stack is empty, calls System.exit(). So if the user keeps pressing back and hits the first screen of your application, pressing back once again would by default exit the app. To avoid this, one needs to override the close() method.

Doing Long Running Work

As described in the Event-Processing section above, the Blackberry UI model is a single threaded one. That means that you cannot do long-running work on it, and instead need to launch a worker thread. This worker thread can update the UI in two ways:

1. Acquire and synchronize on the event lock: To do this, the worker thread invokes Application.getEventLock() and then synchronizes this object to access the UI. While this is being done the Event Thread is paused, so the lock should be held for a really short period of time.

   // on the background thread
   synchronized(Application.getEventLock()) {
       // update the UI
   }

2. Inject an event in the UI message queue: To inject an event, you model it as a class that implements Runnable and inject it into the Event Thread message queue by calling invokeAndWait() or invokeLater(). The event thread would then call the runnable’s run() method at the next available opportunity. While for invokeAndWait(), the worker thread would block till run() returns, invokeLater does not block and returns immediately.

   // on the background thread:
   UiApplication.getUiApplication().invokeLater (new  Runnable() {
       public void run()
       {
           // update the UI - runs on the Event thread
       }
   });

Interprocess Communication

There are two ways in which Blackberry applications can communicate with each other:

1. Using the RuntimeStore: The RuntimeStore is a system-wide volatile storage where applications can place data to share with other applications.
2. Using Global Events: Use Application.addGlobalEventListener() to add aGlobalEventListener to listen to global events. Post a Global Event by callingApplicationManager.postGlobalEvent().

Security Model

Blackberry has a complex security model, owing to its roots in enterprise software. When businesses issue their employees Blackberry devices, they also expect to able to exercise control over what the user is able to do on the device. This is made possible thru a policy which is pushed to the device using BES or the Blackberry Desktop Manager. Such policies can limit the resources available to an application, and to handle that gracefully, applications should:

1. Find out what permissions they have: By callingApplicationPermissionsManager.getApplicationPermissions(). This returns an instance of ApplicationPermissions class which gives all the permissions that are set.
2. Ask for permissions they need: By callingApplicationPermissionsManager.invokePermissionsRequest() and passing it an instance of ApplicationPermissions with the requested permissions set.

Besides this, RIM has marked a number of APIs as controlled APIs. To access these APIs on the device, you must sign your application using a key or signature obtained from RIM. For details, seehttp://us.blackberry.com/developers/javaappdev/codekeys.jsp. On the simulators, these APIs are accessible without code-signing.

Packaging

When you build your app, you create a JAR, alongwith a manifest. Java ME defines certain mandatory and optional attributes that applications should include in the JAR manifest, besides any other app-specific info that maybe present.

However, a Blackberry device cannot directly execute a JAR. It first needs to be converted into a proprietary format file called a .COD file which is essentially RIM’s own version of the JAR. So if you want to run a MIDlet on a Blackberry device, you first need to convert the JAR into a COD file which can be done using the Eclipse plugin or by using the RAPC compiler on the command line. Some more details on using the RAPC compiler are given here.

However, the max size of a COD file is 128 kb with a 64 kb limit on compiled code and 64-kb limit on resource data. In case the compiled code produced is larger than these limits, the compiler breaks the code into mulitple COD files, naming them in increasing numerical order like this:

• HelloWorld.cod
• HelloWorld-1.cod
• HelloWorld-2.cod
• HelloWorld-3.cod
• …

The compiler then takes the numbered files (called sibling COD files), zips them and names the zip as a COD file (HelloWorld.cod above) – this is called the main COD file. There is a max limit to the main COD file too – it can contain up to 127 sibling COD files, thus imposing a theoretical size limit. For more details, seehttp://supportforums.blackberry.com/t5/Java-Development/The-maximum-size-of-a-BlackBerry-smartphone-application/ta-p/502534.

Packaging the application for Wireless or Over-the-Air (OTA) distribution requires more work. For this, Java ME defines an additional manifest called a JAD (Java Application Descriptor) that Java ME applications should provide for OTA distribution. The main purpose of a JAD is for locating a JAR and figuring out its size. Besides the JAR URL and JAR size, the JAD must also contain certain other attributes that are also required in a JAR manifest and may contain any attribute that is in a JAR manifest. For details, see here. Blackberry specific attributes for a JAD are given here. Also, for OTA distribution, you need to extract the sibling COD files from the main COD file. For details see here.

Distribution

Blackberry applications can be distributed in two ways:

1. Direct Connection: Connect the device to your computer and install the app. There are two possibilities here:
   • Using the Blackberry Desktop Manager: The application needs to have a COD file alongwith an additional manifest file called the ALX file.
   • Using a Web Page: For this, you need to put up an ActiveX control called a  Web Loader on the web-page from where you want the installation to happen. The user browses to a web-page on his desktop using IE and the control starts an installer. In case the user visits the page using a Blackberry device, the user is prompted to connect the device to a desktop.
2. OTA: There are two ways in which OTA distribution may happen:
   • BES Push: An organization with a Blackberry Enterprise server deployment can push notifications to Blackberry devices for applications based on policies defined by an administrator.
   • Blackberry App-World: The process is described here.