Unlock the secrets of advanced BlackBerry development

Advanced APIs


The best BlackBerry apps take advantage of the rich set of advanced APIs available on

this platform. The chapters in Part 1 describe some of the most exciting and compelling features available to you. Chapter 1 provides a crash course in building a variety of RIM applications that can access the local filesystem and the Internet. From there, learn how to use the device to shoot photos, record sound and video, and use the captured data in your app. Next, see the wide variety of options available for playing video, animations, and audio content. Connect the BlackBerry to the rest of the mobile world with wireless messaging and email technologies. Finally, incorporate today’s techniques for safeguarding data into your own applications.

Getting Started

Welcome to the wonderful world of BlackBerry app development! Chapter 1 is intended to get you up to speed as quickly as possible, so you can get right into the good stuff, and it assumes no previous knowledge other than a basic grasp of Java. This chapter will walk you through downloading software, setting up your environment, and then give you a quick tour through the basics of BlackBerry app development. You may linger, skim, or skip ahead as your patience demands.

Initial Setup

As with any new language or platform, you will need to install some new software and set up your computer appropriately. There are many different ways to run a successful BlackBerry project. RIM supports only Windows development, but it has done a good job of releasing tools that enable development on a variety of configurations. This section will focus on what I have found to be the simplest and most effective setup for independent development, with occasional notes for alternative choices you might consider.

Getting Java

You will be developing in Java for the BlackBerry, but before we get that far, we need to make sure Java on your desktop is running properly. RIM uses Java for their toolchain—the set of programs that will convert our application source files into a format that can run on the mobile device. Additionally, our Eclipse IDE requires a Java runtime environment.

To see if Java is installed, open a command prompt. You can do this by clicking Start ➞Run, typing cmd, and pressing enter. A black-and-white command prompt window will appear. Type java -version. You should see something like the following:

java version "1.6.0_14"
Java(TM) SE Runtime Environment (build 1.6.0_14-b08)
Java HotSpot(TM) Client VM (build 14.0-b16, mixed mode, sharing)

The specific version number isn’t important, just getting a response. If Java is not installed or is not configured correctly, you will see an error like the following:

'java' is not recognized as an internal or external command,
operable program or batch file.

To install Java, go to http://java.sun.com and look for the Java SE download. You only need to install the Java Runtime Environment (JRE). However, if you plan on doing other Java development besides BlackBerry, you can download the full Java Development Kit (JDK), which also includes the JRE.

Tip: When installing any development software, I suggest you pick an install path that has no spaces in it. For example, instead of installing to c:\Program Files\Java, install to c:\dev\java. This will save you time in the future, as some Java programs and other useful utilities have a hard time working with files that have spaces in their name. Follow this rule for all the other downloads in this chapter, as well.

Once you have downloaded and installed the JRE, try opening another command prompt and typing java -version again. If it still doesn’t recognize the command, you probably need to add Java to your PATH environment variable. In Windows XP, you can access this by right-clicking on My Computer, selecting Properties, clicking the Advanced tab, and then clicking Environment Variables. Make sure the path to your installed java.exe directory is included in the PATH. This will probably be something like c:\dev\java\jre1.6.0_14\bin.

Goldilocks and the Three IDEs

Once upon a time, a developer was evaluating which IDE to use when writing BlackBerry
apps. First she tried the RIM JDE. “Oh my!” she exclaimed. “This IDE is much too ugly!”
Then she tried Netbeans. “This IDE doesn’t understand BlackBerry,” she complained.
Finally, she installed Eclipse with the BlackBerry Plug-in. “Ahhh,” she smiled. “This IDE
is just right!”

The reality is that you can develop in any IDE that you want. The question is how much time and effort you will invest in getting everything to work right. I’ve found that Eclipse is the best platform for doing serious development, and it has only gotten better and easier since RIM released their official Plug-in. I will be using Eclipse for my examples in the rest of this book, and I recommend installing it unless you are already doing BlackBerry development in another environment.

To get started, go to http://eclipse.org. I suggest you download a recent release of the Eclipse IDE for Java EE Developers. Depending on what other kinds of development you do, you may choose to use another package. This is fine, but Eclipse EE contains the most options and will give you the greatest flexibility.

Caution: As of this writing, there are compatibility issues with Eclipse 3.5 (Galileo) and the
BlackBerry JDE Plug-in for Eclipse. If you experience problems, use the older 3.4 (Ganymede)
version of Eclipse. This is currently located in the Downloads page of the Eclipse web site,
where you can select ‘‘Older Versions.’’ You can safely install multiple versions of Eclipse into
separate directories on your computer.

Eclipse doesn’t have a standard Windows installer. Instead, you simply unzip it to a folder on your computer. You could put it somewhere like c:\dev\eclipse. To make it easier to launch, you can right-click and drag the eclipse.exe icon to your desktop or task bar in order to create a shortcut.

When you first launch Eclipse, it will ask you to choose a workspace. You can create one wherever you like. Do not check the option for “Use this as the default and do not ask me again.” One quirk of BlackBerry development is that each BlackBerry app you develop will require its own separate workspace, so you will be switching workspaces as you go through this book.


Plugged In

I have been a fan of Eclipse for many years now, in large part because of its very flexible and powerful Plug-in system. Plug-ins allow developers to tune their workspace for their specific tasks, without needing the bother of relearning a new tool for each new task.

There are currently two ways to install the Plug-in. The first is to go to BlackBerry’s developer web page (currently located at http://na.blackberry.com/eng/developers/) and download the Plug-in as an EXE file. This is the simplest approach, as you can simply download the large file, run it, and then restart Eclipse.

The other way to install the Plug-in is directly through Eclipse. I recommend taking this approach, as it allows you more control over what you install and provides a better way to get updates.

In Eclipse, click the Help menu, then Software Updates. Click the Available Software tab, then click Add site. For the location, enter http://www.blackberry.com/go/eclipseUpdate. The BlackBerry Update Site will display. Several options are available. At a minimum, you will need to select the BlackBerry JDE Plug-in for Eclipse and at least one BlackBerry Component Pack.

Note: You may be asked to enter a user name and password. You can register for a free
developer account on the BlackBerry web site if you have not already done so. This prompt
may appear multiple times, so continue entering the account name and password until it goes
away. The servers hosting the Plug-in are sometimes temperamental and will fail with
unhelpful messages; other times, the installation may appear to hang when it is actually
progressing. If you cannot install through Software Updates, you can try again later, or install
the EXE file directly as described above.

If you have a particular BlackBerry device in mind, pick the Component Pack that matches the software version of that device. All these files are very large, so you should probably only start with a few even if you know you will eventually want more.

Tip: You can find the software version on your BlackBerry by selecting Options, and then About. It should be a value like ‘‘4.5.0.81’’. When selecting a component pack, only the first two numbers are important. The rest will be used to select an appropriate simulator.

 You should restart Eclipse once the install is complete. After it restarts, you will see a new BlackBerry menu option at the top. You will also have access to two new debug configurations: BlackBerry Device and BlackBerry Simulator. Figure 1-1 shows what your Eclipse environment should look like once you have installed the Plug-in and started a new project.

BlackBerry Programs

If you are developing for a personal BlackBerry device, you probably already have the BlackBerry Desktop Manager and the BlackBerry Device Manager installed. If not, installing them is very easy. Go to http://www.blackberry.com and look for the “Desktop Software” download. You may need to select your provider and download the appropriate version for them. You will need to fill out a short form with your name and contact information. Run the downloaded setup file. You may be prompted to install additional software, such as the .NET Framework runtime. Once it’s complete, reboot your computer if prompted. The next time you connect your BlackBerry device to the computer, Windows should automatically install the drivers to access it.
You can launch the BlackBerry Desktop Manager by going to your Start menu and looking under BlackBerry. Depending on your installation choices, the manager may automatically start when you log in to Windows. Figure 1-2 shows the BlackBerry Desktop Manager running.

Simulator Files

Downloading the proper simulator files for the devices you plan to run on is essential, because different types of devices will have different screen sizes and input modes. Even if you have two devices with the same model number, they will behave differently depending on what software version they are running. Simulators are not just important for testing on the computer, though. They also contain essential information for debugging on the actual device.

If you have the physical device you will be using, find the device software version by visiting Options, then About. You will be looking for a version that matches all parts of the version number. For example, if your device has version 4.5.0.81, only use 4.5.0.81, not another version that starts with 4.5.0. You can download simulator packs from the BlackBerry web site. The exact location will change, so your best bet is to visit the
Developers page and look around for the BlackBerry Smartphone Simulators. You will see many, many choices. Pick the one that matches your exact version number and device model and, if applicable, carrier. You’ll need to click through another web form—get used to it, as there is no way to save your information. Download the simulator file, then run it to install. You can install to any directory you like.

To switch to using a new simulator in Eclipse, follow these steps, and restart Eclipse if you are ever prompted to do so.

1. Click the Window menu, then Preferences.
2. Expand the BlackBerry JDE menu and select Installed Components.
3. From the drop-down list, select the component pack that corresponds to your device version. For example, pick 4.5 for a device with version 4.5.0.81. If you don’t see your component pack listed, install it following the instructions in the section titled “Plugged In” earlier in this chapter.
4. Click the MDS Simulator option and navigate to the MDS directory that matches the component pack from Step 3.
5. Click OK. If you already have a project in Eclipse, you will be prompted to rebuild it.
6. Click Run, then Debug Configurations.
7. Create a new BlackBerry Simulator configuration.
8. Click the Simulator tab.
9. From the Profile drop-down, select the item that corresponds to the simulator you installed.

You will now be able to use your device’s proper simulator, and you will have access to high-quality on-device debugging.

The Keys to Development

So far, you have installed everything you need to get started writing BlackBerry software. There’s a catch, though: RIM has marked some of their APIs as restricted, and if your program uses any of these APIs, it will not run on the device unless it has been code signed.

Code signing is covered in more detail in Chapter 9. For now, just be aware that this is often a necessary step in development. It can take from a few days to a few weeks to receive code signing keys, so start this early.

You apply for the keys from the BlackBerry developer web site. Once again, you will need to fill out a form with information. As part of the form, you will be asked for an email address. Be aware that RIM will send multiple emails to this address every time you sign an application. Also, keep in mind that you must sign an application every time you make a change and load it on the device. It isn’t unusual for a large RIM app to generate 50 or more emails on a single signing. Therefore, I strongly urge you to enter an unmonitored email address here, or one where you can automatically delete emails from the signing server. If you use your personal email address instead, it will make your life miserable.

The form also includes a question about Certicom cryptography keys. Certicom cryptography is covered in more detail Chapter 5; for now, you can just say “No” here. You should also pick a unique 10-digit PIN. There is a nominal charge for receiving code signing keys, currently $20. You will need one set of keys for each computer you will use for development. The RIM servers sometimes have problems; if you aren’t able to
complete your order online, you can choose to fax it in instead.

Eventually, you should receive an email from RIM with three key files and instruction on installation. Follow the email instructions. If you run into problems during your installation, follow the links in the email for more support. Once you have installed and registered the keys, you will be all set. You have a limited number of signatures, but the limit is absurdly high, so you don’t need to worry about ever running out.

You will initially install the signing keys for a particular version of BlackBerry device software, such as 4.5 or 6.1. At first, you will only be able to sign applications built for that particular device type. There are two fixes for this, though: first, you can safely use an old version of the RIM signing tool on newer versions of device software. In other words, you can use the 4.5 signing tool on builds for 6.1, but not vice versa. Second, you can copy the files SignatureTool.jar, sigtool.db, sigtool.set, and sigtool.csk from one version of the desktop software to another. This also works to sign applications using both the BlackBerry Eclipse Plug-in and another environment on the same computer.

Tip: If you installed the BlackBerry Plug-in, your SignatureTool should be located in a directory like C:\dev\eclipse\plugins\net.rim.eide.componentpack4.5.0_4.5.0.16\components\bin.

That’s it for setup! You now have all the tools you will need to write, debug, and install your own BlackBerry apps.

and more ... click this download link to get full explanation