Getting started with BlackBerry development in Eclipse

Updated on January 5 after some feedback

After using the BlackBerry JDE plugin for Eclipse for the past couple of months (yes, a bit late on that - I was in a non-develoment job for most of the past year), I can say that - while not perfect - it is currently the best way to develop applications for BlackBerry. 

And even with its flaws, RIM has finally delivered something approaching a world class BlackBerry development environment. So if you are thinking of dipping your toes in BlackBerry development, there has never been a better time.  

I’ll describe setup in a bit, but first a bit of history:

A (very brief and abridged) history of BlackBerry development

The very first BlackBerry handhelds - the 95x and 85x devices - had to be programmed using C++.  RIM made the great choice of using Microsoft Visual Studio as their development environment, which although missing some features VS.NET has today, was still one of the best environments 7 years ago - and definitely (as today) one of the best debuggers around.

When the first Java based BlackBerry handhelds shipped (also the first to run on the mobile phone networks, so the first to function as phones), they shipped a home-grown IDE called the BlackBerry JDE (Java Development Environment).  To their credit, they had a great simulator, good debugger and a rich class library, but the editor itself left more than a little bit to be desired.  Given the availability even then of open-source 3rd party tools like Eclipse, there were constant requests for integration with something else.

With the release of the 4.1 JDE, RIM sort-of answered those requests.  They released a standalone simulator launcher which used JDWP, and so could be integrated with Eclipse (or NetBeans) and the availability of 3rd party BlackBerry Ant tasks meant that you could cobble together a reasonable development environment around Eclipse.  It wasn’t quite as seamless as the JDE, and much harder to setup, but the superiority of the Eclipse environment meant that a lot of developers (including myself) started using this kind of setup for BlackBerry development.  Most developers though - including some of the best BlackBerry developers that I know - continued using the JDE.

Finally in March of 2008, RIM released a plug-in for Eclipse that replicated all the functionality of the JDE in an easy-to-use package.   A lot of people haven’t looked back since. I’m one of them. So let’s get started.

Setting up the JDE Plug-in

As I implied, setup is very easy.
1. Get and install the JDK from Sun (but you probably already have that, right?)
2. Download and setup (i.e. unzip) Eclipse 3.4 (the regular Java version is fine for BlackBerry development)
3. Download one of the JDE plug-in packages from RIM’s BlackBerry Developer Zone (I recommend the one that includes all the JDE versions - at minimum you’ll want something that includes 4.3 to maintain compatibility with the largest installed base of devices, but probably also 4.7 so you can develop some touch-aware functionality for the sexy new touch-screen Storm)
4. Install the JDE plug-in.  Don’t worry about which workspace you use to install the plugin, it’ll always appear in every eclipse workspace once installed in on.  There’s a Word Doc on the BlackBerry site with instructions (Word?  Ah, RIM), but also a Google-docced version here

And you’re ready to go!

Your first BlackBerry project

This will be very quick, I’m focusing on the mechanics of project setup, and so won’t explain the code at all (look for lots of other posts about that!)

Creating the project

1. Create a new BlackBerry project (from the Eclipse menu choose File->New->Project)
2. Choose BlackBerry->BlackBerry Project
3. Click Next, and Name your new project (I called mine HelloWorldBB) and finish the new project wizard

What a basic project looks like

You’ll see a couple of things listed under your project.  One is a folder called src, this is the default name for Eclipse source directories.  The other is a link to a library called NET_RIM_BLACKBERRY.  This is the BlackBerry runtime library, which includes the all the Java ME classes.

Configuring the JDE Version

Now is as good a time as any to configure a specific version of the JDE.  To do that from the BlackBerry menu select Configure BlackBerry Workspace (really this is just a shortcut to Window->Preferences->BlackBerry, so go that way if you’re an experiened Eclipse user and feel more comfortable)

From this dialog choose Installed Components and select a version of the JDE.  Note that BlackBerry apps are backwards compatible - i.e. a 4.3 app will run on a 4.7 device like the Storm - but you won’t be able to use any more recent APIs.  The usual tradeoff with technology evolution.

Everything else we can leave as default, I’ll explain the other options in a later post.

Writing the application

Now to actually write the code.  We’ll make 2 classes - an application and a main screen.  This is where Eclipse’s richer environment will really start to pay off.

1. From the menu choose File->New->Class

Fill in as much of this dialog as you want.  For our purposes, the name of the class (HelloWorldApplication), a package (Eclipse sensibly warns us not to use the default package - I chose com.thinkingblackberry).  And as the superclass choose net.rim.device.api.ui.UiApplication.  And finally (you JDE developers will love this) - check the box that next to public static void main(String[] args), and the one next to Constructors from superclass and we’ll get a main method and a default constructor stubbed out.

Ok?  Now lets create the screen class, and then fill the java files in.  For the screen class use the same package, change the name - obviously (HelloWorldScreen in this case) - and as the superclass use net.rim.device.api.ui.container.MainScreen.  Don’t check the main checkbox this time, do check the Constructor checkbox

So we’ve got 2 classes.  All that’s left is to fill in the methods.

HelloWorldApplication should look basically like this:

package com.thinkingblackberry;

import net.rim.device.api.ui.UiApplication;

public class HelloWorldApplication extends UiApplication {

	public HelloWorldApplication() {
		HelloWorldScreen screen = new HelloWorldScreen();
		pushScreen(screen);
	}

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

}

HelloWorldScreen should look like this:

package com.thinkingblackberry;

import net.rim.device.api.ui.component.LabelField;
import net.rim.device.api.ui.container.MainScreen;

public class HelloWorldScreen extends MainScreen {

public HelloWorldScreen() {
add(new LabelField("Hello World!"));
}
}

Building

Now to compile? Well, that’s one of the great things about Eclipse.  It’s already compiled!  (You’ll have to do a little extra work to build for the device, but you can run on a simulator right now!).  So…

Debugging

Click on the down arrow next to the debug button in the toolbar and choose Debug Configurations.  Note that there are 2 ways to debug BlackBerry apps - in a simulator, or on a device.  The on-device debugging works great, but there are more steps involved in loading your app onto your device, so we’ll just use the simulator for now.

Click on the BlackBerry Simulator icon, and click the New Debug Configuration icon.

There are a lot of options here, which should be familiar to JDE users.  For now we’ll just click the Simulator tab and select a device simulator to use.  The list is determined by what you selected as your JDE version.  In my case I chose 4.3, so I’m limited by default do the 8100 series - Pearl devices.  You can add other simulators, which are available as separate downloads from RIM.

Choose Apply, then Debug (from the bottom of the dialog window), and the simulator will start, with your app loaded. You’ll have to scroll to the icon and launch your app - just like on a real device.

We just have the default BlackBerry app icon because we didn’t specify another one, but there’s your first JDE Eclipse plug-in application!
Ok, it’s not the most exciting application - but the first steps for building BlackBerry apps of all sizes are the same, so play around. The javadoc integration in Eclipse helps a lot (just hover your mouse pointer over any class or method name).

Do I still need to get the JDE?

This is a good question, and there are still a few reasons you probably still want to download and install the standalone JDE.

1. There are some problems with the Eclipse plug-in. Things that you can do with the JDE that don’t work with the plug-in yet. Some of these have workarounds, some don’t. I’ll explore these in future posts.

2. It contains all the BlackBerry sample projects.  The Eclipse plug-in does not.  If you’re a new BlackBerry developer, or just want to refer to one of the samples, then downloading the JDE is a good idea.  I still keep a copy around, just of the latest version.

3. You’re working with other developers who don’t use the Eclipse plug-in.  This is one of the small drawbacks to the plugin that I alluded to earlier - it stores the BlackBerry project files in slightly different locations than the JDE does.  More on this in another post, but basically it’s a good idea to have your whole team using one environment or the other, but if for some reason you need to build a JDE-based project once in a while, you’ll want the JDE.

4. The Eclipse plug-in only supports BlackBerry OS 4.3 and later. This will be less and less of an issue as time goes on, as 4.3 was introduced with the Pearl (8100 series), and all later devices run 4.3 or higher. But if you must support older devices, the JDE (or the older Eclipse/JDWP Frankenstein method) is the way to go.

What now?

Stay tuned. I’ll write some more posts exploring Eclipse and BlackBerry more in depth - most of the tricks I’ve been using all these years still apply with the JDE plugin, and there are a lot of productivity-enhancing features in Eclipse to talk about.

I’ll also be writing more about BlackBerry application architecture and development in general.

In the meantime, the BlackBerry developer zone is a great location for more info on BlackBerry development.