Build Your First BlackBerry Application

he BlackBerry wireless handheld device by Research In Motion (RIM) has quickly gained popularity among mobile professionals. With its "Always On, Always Connected" approach, it enables corporate users to connect to their e-mail systems, including Lotus Domino and Microsoft Exchange, and other mission-critical systems (e.g., instant messaging) using a General Packet Radio Service (GPRS)-based wireless connection.

BlackBerry supports Java 2 Platform, Micro Edition (J2ME) and ships with a complete Connected Limited Device Configuration/Mobile Information Device Profile (CLDC/MIDP) implementation. Although Blackberry devices run applications that use only the standard MIDP APIs (commonly referred to as MIDlets), developers can also tap into BlackBerry-specific APIs to take advantage features such as sophisticated user interfaces.

This article introduces the freely available BlackBerry Java Development Environment (JDE), which allows you to develop, debug, and test BlackBerry applications. It goes on to demonstrate how to create a simple HelloWorld application that exploits some of BlackBerry's own APIs.

The BlackBerry JDE
The BlackBerry JDE includes an integrated development environment (IDE) for BlackBerry applications and Blackberry simulation tools that you can use to see exactly how the applications will act on a real BlackBerry device. The BlackBerry JDE also contains a number of working sample applications.

Before moving on, download the BlackBerry JDE. At the time of this article's writing, it was in version 4.0.1.

Installation of the JDE requires that you have the Java 2 Platform, Standard Edition (J2SE) v1.4 running. InstallShield walks you through the JDE installation. When you choose a complete installation type, it should create a Research in Motion program group in your Start menu.

Prepare to Say Hello
Start up the Blackberry JDE by going to Start -> All Programs -> Research In Motion -> BlackBerry Java Development Environment 4.0 -> JDE. You should see the RIM development environment. Use the Files tab of the Workspace view to drill down into the com\rim\samples\device folder. There you will see a number of sample application projects that you can dissect to your heart's content. One of them is a HelloWorld application (see Figure 1).

Figure 1. Browsing Through the JDE's Samples

Since life is not very educational if everything is handed to you on a silver platter, this tutorial demonstrates how to build your own HelloWorld application—which actually does exactly what the HelloWorld application that ships as an example does.

Figure 2. Creating a New Workspace

Like many other IDEs, Blackberry projects are collectively housed in units called workspaces. Create a workspace by going to the File menu and choosing the New Workspace… option. Specify a Workspace name of HelloWorldWorkspace as Figure 2 shows. Here, you can also specify a directory in which to create the workspace. This article uses the default directory locations provided by the IDE.

Figure 3. Creating a New Project in the HelloWorldWorkspace Workspace

After creating the new workspace, choose the Project menu and then the Create New Project… option. Name the project HelloWorldProject as Figure 3 shows.

Next, choose the File menu and the New… option. In the subsequent Create new file window, make sure the Java File type is selected and specify "HelloWorld.java" for the File name, as Figure 4 shows.

Figure 4. Creating a New File Named HelloWorld.java

At this point, the IDE creates a barebones Java class with the following code in it:

 package ;  class HelloWorld { } 

Of course, this code does nothing. It is your job to populate the HelloWorld class with something worthwhile (more on that in a bit). But before that, you need to associate your HelloWorld java file with the HelloWorldProject you created earlier. To do this, simply right click in the code editor area and select the Insert into Project option. From the subsequent project selection window, choose the HelloWorldProject.

Say HelloWorld
At this point, you are ready to create your HelloWorld application. Since you want your HelloWorld application to provide a graphical user interface (GUI), you need your HelloWorld class to extend the net.rim.device.api.ui.UiApplication class. (Download the code for the HelloWorld application from the zip file that accompanies this article.)

Your BlackBerry application starts like a typical J2SE application does, with a main method. If you are an experienced MIDlet programmer, you should notice something weird here. A MIDlet starts at the startApp() method, but BlackBerry applications start at main:

 class HelloWorld extends net.rim.device.api.ui.UiApplication  {     public static void main(String[] args)     {         HelloWorld instance = new HelloWorld();         instance.enterEventDispatcher();     }       public HelloWorld()      {   pushScreen(new SalutationScreen());     } } 

The first thing you do in the main method is create an instance of your application by calling its constructor. The constructor uses the HelloWorld class' parent class (UiApplication) method of pushScreen to display a screen. You haven't defined the SalutationScreen class yet, but rest assured, you'll get to that. After calling the constructor, call your new instance's enterEventDispatcher method. This method allows your application to start handling various events that the BlackBerry device may send to the application (e.g., UI-centric events).

Create a new class in the HelloWorldWorkspace and HelloWorldProject, as you did before, but this time call the new class SalutationScreen.java. The SalutationScreen class is what will actually present a Hello World message to your application user. SalutationScreen.java is shown below:

 import net.rim.device.api.ui.*; import net.rim.device.api.ui.component.*; import net.rim.device.api.ui.container.*;  class SalutationScreen extends MainScreen {     public SalutationScreen()     {         super();         LabelField applicationTitle =              new LabelField("Hello World Title");         setTitle(applicationTitle);         RichTextField helloWorldTextField = new RichTextField("Hello World!");         add(helloWorldTextField);     }     public boolean onClose()     {         Dialog.alert("Bye World!");             System.exit(0);            return true;     } } 

The SalutationScreen Class Dissected
The SalutationScreen class extends from the net.rim.device.api.ui.container.MainScreen class, giving your simple application consistency with other native BlackBerry applications. It also provides such features as a default menu with a Close menu item for exiting out of your application, which the user also can invoke by pressing the BlackBerry Escape key.

To add a title to your simple application, create a new net.rim.device.api.ui.component.LabelField object:

 LabelField applicationTitle =              new LabelField("Hello World Title"); 

The code above contains a field with the text "Hello World Title". You can always learn more about this API call, as well as other APIs, by taking a look at the API Reference that installed with the JDE. To view the API reference, go to the Help menu and choose the API Reference option or simply press shift+F1 (see Figure 5).

Figure 5. Using the JDE's API Reference

After creating your LabelField GUI component, add it to the screen by using the add method you inherited from your ancestor classnet.rim.device.api.ui.Screen.

You also inherit the onClose method from the net.rim.device.api.ui.Screen, which is fired when your screen (Salutation Screen) closes. In reaction to the closing event, the application uses the alert method of the net.rim.device.api.ui.component.Dialog class to display a popup on the screen stating a message of "Bye World!":

     public boolean onClose()     {         Dialog.alert("Bye World!");             System.exit(0);            return true;     } 

A Real World "HelloWorld"
At this point, you are ready to see your simple application in action. But before doing so, you need to make sure that your HelloWorldProject has been marked as Active. Doing so tells the BlackBerry simulator which applications it should run. Go to the Project menu and select the Set Active Projects… option. Make sure the HelloWorldProject is checked and click OK.

Figure 6. Build the HelloWorldProject and Launch the Simulator

Next, go to the Build menu and select the Build All and Run option (see Figure 6).

Figure 7. Launch the BlackBerry Simulator

Now, you should see the BlackBerry Simulator launch as shown in Figure 7.

At this point, you can use the up and down arrow keys to find your HelloWorldProject application amongst the installed applications on the simulator. The up and down arrows simulate the thumb wheel of a real BlackBerry device (seeFigure 8).

To choose the application, you can either press the Enter key on your keyboard or the Enter button on the simulator's keyboard. To see how the BlackBerry simulator closely mimics the real life device, you can alternatively click the thumb wheel of the emulator (as shown in Figure 9) to launch the HelloWorld application.

Figure 8. Pick the HelloWorldProject Application

Figure 9. Thumbwheel of the Simulator

Whichever method you chose to launch the application, your efforts should yield the HelloWorld application on the screen of your emulator (see Figure 10).

To exit out of the application, click the Escape button of your keyboard or the Escape button on the side of the BlackBerry emulator. You should see the Bye World! alert as shown in Figure 11.

Clicking OK should bring you back to the application chooser screen. You can click the File menu and the Exit option to exit out of the simulator.

Figure 10. The HelloWorld Application Launched

Figure 11. The Bye World! Alert

Multiple Simulation Environments Included
By default, the BlackBerry JDE 4.0.1 uses the BlackBerry 7290 device simulator, but it offers a large number of BlackBerry simulation devices. To choose one, select the Edit menu and the Preferences… option. In the subsequent Preferences window, choose the Simulator tab and pick among the list of available device profiles. Figure 12 shows the selection of the BlackBerry 7100t profile.

Upon a subsequent run of the simulator, you will be able to run the HelloWorld application on the chosen simulator device (see Figure 13).

Figure 12. Choose a Profile for Device Simulation

Figure 13. Run Your Application on a Simulator

Just Scratching the Surface
This article demonstrated how to develop Java applications for the BlackBerry device. The BlackBerry JDE provides a powerful environment in which you can develop, debug, test, and simulate applications.

Like many IDEs, the BlackBerry JDE provides developers with such features as code completion for ease of development. It also lets you look under the hood of your application during the debugging process, allowing you to set breakpoints, step through code line by line, and view variable state information as illustrated in Figure 14.

Figure 14. Creation of Breakpoints and Variable Value Inspection

The simple Hello World application showcased in this article barely scratches the surface of the rich applications you can create for the BlackBerry. Being familiar with the BlackBerry JDE, you should now feel comfortable going through the numerous sample applications the JDE offers.

Kulvir Singh Bhogal works as an IBM consultant, devising and implementing Java-centric solutions at customer sites across the nation.