When I’m running an application on a BlackBerry device — and I hit the red key — my app disappears, and the menu screen reappears. I’d guess that my app’s screen was popped off the BlackBerry screen stack, so onClose() was called and my app cleaned itself up neatly, right?

Wrong.  The application was merely sent to the background.

I assume this behavior is mentioned somewhere in the bowels of the RIM documentation (although I’ve read quite a lot of it, and I haven’t seen mention of this). Nor do the sample applications appear to deal with it. I just figured it out when my colleague Andrew Davison sent me a game that plays music in the background. It was a tad loud, so I instinctively tried to shut it off in one click using the red key. And the game went away, but the music kept right on playing…

It reminds me of a little something I read in the PodTrapper story:

My curve has 32MB of RAM and 64MB of flash. The flash can be used for paging if it’s available, but on my device only about 20MB of it is, and that fills up fast installing applications (PodTrapper alone is 350k). Realizing that the OS and other apps also have to fit in RAM, leaking a 100kb string becomes a huge problem. There are lots of forum posts by people trying to figure out why their phone keeps running out of memory and needs to be rebooted. It’s a large enough problem that there are apps for automatically restarting your phone. I can definitely see why Apple has been hesitant to open up background processing on the iPhone. It’s really easy for bad developers to make the whole platform look bad.

Personally, I think it’s kind of cool that you can run apps in the background on BlackBerry, and send them to the foreground and back. However, I think the simplest, default behavior should lean towards cleaning up the app neatly, while sitting on memory and processes when your app goes out of scope should be a special behavior that advanced developers can request.  Not the other way around.

So what about that red key?  What if you’re developing a game or animation that makes no sense in the background, and you just want it to clean up whenever the user dismisses it?

Andrew proposed the following solution (for use in a subclass of Screen):

// keycodes for the green and red keys
private static final int GREEN_KEY = 1114112;
private static final int RED_KEY = 1179648;

protected boolean keyDown(int keycode, int time)
// terminate the game if the green or red keys are pressed
{
// System.out.println(“keyDown: ” + keycode);
if ((keycode == GREEN_KEY) || (keycode == RED_KEY)) {
isRunning = false;
return true;
}
return false;
}  // end of keyDown()

***

That works, but on some level I couldn’t help but feel like it’s absurd of RIM to expect developers to check for the key codes of the red key and green key instead of providing some sort of help.  This has got to be a fairly common scenario, doesn’t it?

Poking around the API a bit, I found it:  In your Application subclass, you implement deactivate().  Here’s the JavaDoc:

public void deactivate()
Handles backgrounding event.
The system invokes this method when sending this application to the background. By default, this method does nothing. Override this method to perform additional processing when being sent to the background.

So, if you’re writing an application that makes no sense in the background, then you implement this method and have it perform the app’s cleanup and shutdown.

Like so many aspects of BlackBerry programming, it’s quite simple once you notice the problem and figure out the trick.

I’m looking for one engineer (who has worked with BlackBerry) for a fun little project. It’s a paid project, not just a hobbyist idea.

If you’re interested, please leave a comment, and I’ll email you.  Thanks!

For fun, I’ve submitted one of my sample games (Ladybug Maze) to BlackBerry App World.  This is mostly an experiment to try out how BlackBerry App World works — I doubt many people will pay $2.99 for this simple little game. But who knows?

Suppose you’d like to create a BlackBerry application that will launch when you send an SMS message to the appropriate port.  It’s possible, but there are a number of non-obvious (and not-necessarily-documented) tricks.  I spent a few too many hours on experimenting to figure out precisely what works, and I’m posting my notes here to save you some time:

1. Apparently your application has to be a MIDlet, not a “CLDC application” (RIMlet).  I was a little surprised when I read this in the BlackBerry Java Dev forum, since it would undoubtedly be trivial for RIM to allow either type of application to register with the PushRegistry and get launched.  So I did a few tests (with a “MIDlet-Push-1″ Jad property analogous to the way the RIMlet uses the “MIDlet-1″ property), and, indeed, the PushRegistry doesn’t seem to work for RIMlets, but it works fine for MIDlets. (Note: it’s still theoretically possible that there’s a way to make it work for RIMlets, but I couldn’t find the trick.)
2. Adding a custom property to your Jad file is really easy if you know the trick. The trick is that (in the BlackBerry JDE) you can add the Jad file to the project (in the same way you add source files and images).  Once you’ve added the Jad file to the project, you can add properties and then they won’t get overwritten when you rebuild.  But before you add it, you should modify the project properties (setting the application type to MIDlet) and then build the project once, so that it will create for you a correct initial Jad file to use.
3. Before your application closes, you should dynamically re-register with the PushRegistry.  This was the trickiest one to guess!  If your MIDlet is launched by the PushRegistry — and you open the corresponding connection to read the SMS message that launched your MIDlet — this automatically unregisters your MIDlet from the PushRegistry.  With other handsets, once you’re registered with the PushRegistry (either statically in the Jad or dynamically from within the application), you stay that way until you actively unregister it.  But not BlackBerry.  Or at least not with the BlackBerry simulator that comes with the BlackBerry JDE 4.2.0.  I assume the behavior is the same in other versions and on the device, but I’m not certain…
4. How do you simulate the SMS to test the application launch with the PushRegistry?  I explained that here.

If you’re writing a BlackBerry Java application that sends and/or receives SMS text messages, naturally you need to be able to test the application on the simulator.  And naturally the simulator doesn’t really send SMS messages, so you need to know how to get the simulator to exchange simulated SMS messages with another instance of the simulator.

This is very easy to do.  You can do it with the SmsDemo that comes in the BlackBerry JDE’s sample applications bundle — even though the SmsDemo’s JavaDoc seems to imply that you can’t.  If you look in the code of SmsDemo.java (usually found at C:\Program Files\Research In Motion\BlackBerry JDE <version>\samples\com\rim\samples\device\smsdemo), the JavaDoc says the following:

This program requires the associated server component found in the com.rim.samples.server.smsdemo package under the samples directory in your JDE installation.

That’s not precisely true.  It doesn’t require the server component — it can actually send demo messages from one instance of the simulator to another, as long as you set the sms-source-port of the one to be the sms-destination-port of the other, and vice-versa.  There are just a few quick steps and notes for launching the two instances:

The simulator executable is called “fledge.exe” and it is found in the simulator directory of the JDE installation (usually under C:\Program Files\Research In Motion).  You can run fledge from the command line or from a batch file with command line options specified with the usual Windows style (with a leading “/” instead of a “-” for you *nix developers).  Here’s an example of the command to launch the first one:

C:\BlackBerry\my-simu-directory-1>”C:\Program Files\Research In Motion\BlackBerry JDE 4.2.0\simulator\fledge.exe” /app=”C:\Program Files\Research In Motion\BlackBerry JDE 4.2.0\simulator\Jvm.dll” /sms-source-port=5000 /sms-destination-port=5001

Then launch the second instance (from a different directory) with the source and destination port numbers inverted.

Since the fledge executable requires you to specify the JVM DLL in the “/app” option, you might think it would be easier to just navigate to the simulator directory and launch it from there.  The problem is that the simulator stores a set of files in the directory you launch it from, and it won’t let you run two instances simultaneously from the same directory.  The trick is to either write a batch file to launch both or — my personal favorite — an Ant target, such as the following:

<project default=”sms-run”>

<property name=”jde.home”
value=”C:\Program Files\Research In Motion\BlackBerry JDE 4.2.0″
/>
<property name=”model” value=”8100″ />
<property name=”build.root” value=”C:\BlackBerry\smsbuild” />

<target name=”sms-run”>
<!– run two simulators that can communicate with one another via sms –>
<mkdir dir=”${build.root}\sms-simu-1″/>
<exec executable=”${jde.home}\simulator\fledge.exe”
dir=”${build.root}\sms-simu-1″
spawn=”true”>
<arg value=”/app=${jde.home}\simulator\Jvm.dll”/>
<arg value=”/handheld=${model}”/>
<arg value=”/app-param=DisableRegistration”/>
<arg value=”/app-param=JvmAlxConfigFile:${model}.xml”/>
<arg value=”/pin=0×2100000A”/>
<arg value=”/sms-source-port=5000″/>
<arg value=”/sms-destination-port=5001″/>
</exec>
<mkdir dir=”${build.root}\sms-simu-2″/>
<exec executable=”${jde.home}\simulator\fledge.exe”
dir=”${build.root}\sms-simu-2″
spawn=”true”>
<arg value=”/app=${jde.home}\simulator\Jvm.dll”/>
<arg value=”/handheld=${model}”/>
<arg value=”/app-param=DisableRegistration”/>
<arg value=”/app-param=JvmAlxConfigFile:${model}.xml”/>
<arg value=”/pin=0×2100000B”/>
<arg value=”/sms-source-port=5001″/>
<arg value=”/sms-destination-port=5000″/>
</exec>
</target>

</project>
To run this example, just create the ${build.root} directory (here it’s “C:\BlackBerry\smsbuild”), and change the JDE version number to whichever version you’re using.  If you’re not using BlackBerry JDE 4.2.0, then you’ll also have to change the model number to some model that has a corresponding xml file in your JDE’s simulator directory (or just delete the model-related arguments).

Also note that when you launch the second instance of the simulator, it will give you an error message because the first instance is using the port that the simulator normally uses to communicate with the debugger.  Just select “ignore”, as explained in the BlackBerry knowledge base here.  I tested a few of the other fledge options (which I found by running fledge /help from the command line), but none of them seemed to allow me to switch the port number for the debugger or to just eliminate the message from being displayed.

The last thing to note is that the SmsDemo application obviously has to be installed on the simulator you’re using.  If you open the “samples” project in the JDE and select “build all” or “build all and run” from the “build” menu, then the application will be installed on the simulator.  You only need to do it once, and the SmsDemo will be there (in the simulator’s Applications menu) when you run the simulator from the command line or the Ant script.

Both instances must be running the SmsDemo application in order for them to communicate with one another — sending a message from one won’t launch the application on the other.  The destination address you enter in the SmsDemo application doesn’t matter — it appears to be ignored.  The port information above directs the message to the other simulator, and the SMS address string (in the SmsDemo code) specifies an application port number so that the message is directed to the SmsDemo application on the other simulator (and not to the other simulator’s “messages” folder).

If you’ve spent any time studying best practices in software engineering, it can be jarring to discover how far the reality of software production often diverges from the ideal.  It isn’t rare to see code in production — stuff that’s critical to a company’s business — that isn’t even under version control, much less documented with bug-fixes tracked to requirements, testing infrastructure in place, etc.

Personally, I like doing reverse-engineering (restoration of lost knowledge) — taking a bundle of mysterious old code and figuring out exactly how it works and what it’s doing, so that it can be upgraded or replaced.  I’ve done it for more than one company.  However (at the risk of cutting down on the need for this sort of work), I’ll tell you that it’s cheaper to fix “free-fall code” while you still have the engineers who designed it on hand, before a reverse-engineering effort becomes necessary.  It’s a little like an old building with electrical wiring that’s not up to code:  replacing all the wiring seems expensive for something that yields no visible results, yet it’s cheaper than leaving the old wiring in place to catch fire and burn the building down.

How does free-fall code get all the way to production?  In my experience, there are a couple of main causes:  First, a lot of code bases are still in use that were actually started before many best practice ideas became commonplace, and overhauling the process just never made to the company’s priority list.  Second, small start-ups often have no choice but to produce code that way.  Typically, you have a critical deadline and just one engineer (who is required to make a superhuman coding effort to get it done).  It’s release or perish, so there’s no time for frills like documentation, precise requirements (which you don’t need anyway if you have only one engineer), or tests.

One company I worked for had recently grown from start-up size to “real company” size, and one of the higher-ups decided that we should try to keep acting like a start-up because “start-ups produce code so much more efficiently.”  That is wrong, wrong, wrong.  Start-up mode means sacrificing a long-term code-maintainability strategy for the sake of the shortest-possible-term results.  And for every start-up that makes it, there are plenty that don’t, so they’re not that amazingly efficient if you look at the big picture: not only do companies have to pay more later to get their missing best practices on track, but also the failed start-ups represent an inefficient waste of coding that balances out the amazing results of those few that succeed.

So the moral is that once your start-up has passed that first hurdle — and has a little cushion of money to spend — the critical task is to move the engineering department from start-up mode to something scalable, efficiently and effectively.

That’s the critical task for the internal operations manager, that is.  The overall #1 priority for your start-up (once you have a little cushion of money) is to make sure that your business strategy makes sense and is on track.  Ideally, your start-up started with a business visionary who knows what to sell and how to sell it, a gifted manager who can run internal operations and grow the company wisely to meet the strategy, and an excellent engineer who can make it so — covering all of the engineering bases until the company is in a position to grow.  I know this because I’ve worked for a number of start-ups, and I’ve kept my eyes open the whole time.  It’s volatile work (as employment goes) but on the plus side there’s never a dull moment.

It’s easy to underestimate the importance of having a talented manager running internal operations — especially in a small company where others are producing visible results like writing an application or selling a contract.  But teamwork and morale are critical when growing a small company.  You can’t afford to pay people to work at less than full capacity, so everybody has to be on the same page.  As soon as you have more than one engineer, you need a skilled manager who will make sure that everyone knows (and is in agreement on) what you’re implementing and on who’s doing what, with clear requirements and objectives.

(To give you an idea of how important clear requirements are to the efficient production of code, note that in Switzerland there’s now a conference covering nothing but requirements engineering.  At least that’s what I think it’s about, given my current level of German comprehension…)

In the first stage of growing your company from “start-up” mode to “real company” mode, you’ll want to hire a QA engineer (in addition to hiring more engineers for R&D).  The QA engineer should be a bit of a jack-of-all-trades (kind of like your initial development engineer), who can write the requirements (based on verbal discussions with the business or sales personnel), get business/commercial and R&D to agree on the requirements, write a test plan, install bug-tracking software, set up version control and a nightly build (unless someone on the development team is doing that), set up a unit testing framework, and get everyone’s agreement on a set of coding and documentation guidelines.  In the early stages, manual testing can be outsourced as long as you have a clear test plan.  The internal operations manager should work closely with the QA engineer to decide on priorities and to ensure that R&D and QA cooperate with each other.  This will get your initial growth off on the right foot.

Now, what if you’re moved to a new project and you discover that your company is already dangerously dependent on a block of free-fall software?  Or what if your company buys a code block that has no tests or documentation, and it’s thrown in your lap?

It’s a little like the situation above (the company’s initial growth spurt): you catch the free-fall code by building a QA framework around it.  First, put it under version control, and second, write a clear document explaining exactly what you need to do in order to build and run the code, including all the tools and other software needed, specifying the hardware and software version numbers.  The document should be complete enough that an engineer who has never seen the code before can take it out of version control and build and run it on virgin hardware.  If you can’t do that, then you are missing critical (burn-down-the-building level) information.  If you still have access to the engineers that wrote the code, it’s a lot cheaper to get their input on this document than it is to hire specialists to figure it out, especially if the code is designed to use proprietary and/or now-obsolete hardware or software.

Once the code is under version control and you’re sure it can be rebuilt, the emergency stage is over.  The next (hopefully more relaxed) stage is to determine your objectives for the software, in terms of bug-fixes, performance, and upgradability.

If the code is working with no major problems, it may just need a bit of documentation to explain what it does and how it works.  If the code is not documented at all, that may be a sign that the engineer who wrote it is not particularly skilled at documentation.  (This is not a failing in engineering terms — often excellent engineers aren’t very good at explaining how code works, even to other engineers — it’s a bit of a separate skill, just as being able to manage engineers is a separate skill that is not directly related to engineering ability.)  If you have access to the original engineer, just assign another engineer to write the document (with input from the person who wrote the code) at a rate of about one or two days a week until it’s done.

If you need to fix or upgrade your free-fall code, then the next step is to analyze it, and get an engineering estimate on the effort/risk involved in fixing it vs. the effort/risk involved in retiring and replacing it.  The fixing estimate should include the effort to write a set of automated regression tests for the code.  Then management should use this estimate to decide which course to take.

If the only problems are a handful of bug-fixes and very specific performance bottlenecks, then often a surgical approach is better than refactoring, particularly when dealing complex, fragile old code.  As an engineer, when you look at old spaghetti code, you will certainly see things that are inefficient and ugly, and it is soooo tempting to just start ripping it out willy-nilly and rewriting it.  But the problem with that approach is that you will almost certainly lose information.  Nine times out of ten, you’re right that the ugly code is just due to inefficient design and/or hastily patching new features onto code that wasn’t designed to accommodate them.  But one time out of ten, the counter-intuitive code was written that way for a real (yet non-obvious) reason, and if you don’t have access to the original engineers, you can’t be certain exactly which parts those are.  Even if you’re an excellent engineer (which I assume you are), and even if you’ve set up a framework of automated tests before you begin (which you should!), undocumented code may potentially be doing things you’re not aware of — hence major changes bring the risk of breaking functionality that is not covered by your tests. If your objectives are punctual, then focus on fixing the parts that are broken, and for the rest, remember the old adage about what to do with stuff that ain’t broke.

Sometimes, however, you will need to refactor the old code.  Keep in mind that code can be optimized for a number of different objectives (readability, speed, memory use, extensibility in various directions, etc.) and these optimizations are not necessarily compatible with one another.  It is a direct corollary that all code can be refactored in a number of different possible ways.  Therefore, any refactoring you do should be done with specific objectives in mind that you’ve discussed and prioritized with your manager.  For example, you may need to re-write a section to accommodate a requested new feature, or to make the code compatible with the latest version of some third-party software that it’s dependent on, or you may need to clean up an inefficient design for clarity if the code is particularly buggy and needs a lot of maintenance.

Of course, that brings us to the other possibility: retire and replace the free-fall code instead of trying to fix it.  Even if you’re planning to replace an application entirely, you should still document it carefully before retiring it, in order to avoid information loss.  Don’t imagine that you can skimp on the build instructions document (mentioned above) because — when the old code itself is its own spec — the development engineers may need to be able to experiment with the old code in order to determine exactly what it does.

Once you’ve done these things, you’re on your way to having a QA safety net to catch your free-fall code.  It’s an up-front investment in best practices that will pay off in terms of decreased risk and increased software development efficiency.

I just received my official certificate in the mail from the American Software Testing Qualifications Board certifying that I’m now a Certified Tester, Foundation Level. The funny part is in the letter where it says that I’m now entitled to put the letters “CTFL” after my name on my business cards and letterhead. No offense to the ASTQB (and ISTQB) folks, but the test is really easy, so I’m not sure how impressive it will look (especially following the old “Piled Higher and Deeper”).

That said, I felt the ISTQB course was fun and worthwhile. I was working for a QA consulting company in Switzerland, and instead of taking a formal course, the employees organized an informal study group. One colleague divided the syllabus into lessons, and then we met once per week to discuss that week’s assignment. Most of the concepts in the Foundation Level syllabus are the type of things that are simple (once you read them) but you might not have thought of spontaneously. So it’s interesting to get together among colleagues and discuss. For someone like me (who has primarily seen QA from the outside, while working in development), it’s useful to take the time to understand QA from the high level concepts to the practical techniques.

I didn’t take the test with the rest of my “class” because I left Switzerland before we were done. But since the ISTQB is an international board, it was simple to just take the test after arriving in the U.S.

Even though I’m still playing with MIDP for the moment, it’s fun (and instructive!) to look over the shoulder of some of the people developing games for other device platforms.  I’ve done a little bit of work on the Android platform, and naturally I’d like to know what’s up with the iPhone as well.

So I picked up a copy of iPhone Games Projects by PJ Cabrera (and others).  This book is unusual for a computer book in that they gathered up ten highly successful iPhone game developers to give their best secrets and advice, so it gives higher-level project strategy ideas instead of spelling out all of the technical nitty-gritty.

Overall, the book answers the following questions:

• What makes an iPhone game great?
• How do you plan and execute a successful professional iPhone project?
• How do you optimize for the iPhone?

The authors all present different perspectives on the subject, which naturally invites the reader to contrast them and think about their ideas!

My favorite was Mike Lee’s chapter on code optimization.  In addition to giving specific information about iPhone optimization, he gave something of a meta-strategy of optimization based on the fact that optimization is relative — you can optimize for a number of different things (speed, code size, readability, cross-platform portability, etc.) and savings in one place often means a cost somewhere else.  That advice doesn’t just apply to iPhones — it’s a critical point to keep in mind for mobile development in general since resources are limited.  For example, in a business application in which speed of menu navigation is critical, I might load all of the images into memory during the opening splashscreen, but that same trick wouldn’t be an optimization in a game that’s tight on memory.  Here’s a taste of what Lee recommends:

An application is only as fast as its slowest part, and even trivial applications contain a mindboggling web of parts. Shaving off picoseconds at random is like spitting in the ocean.  You’re much more likely to get in trouble than you are to hit a fish.

Rather than worry about the efficiency of every line of code, worry about your own efficiency.  Adding code complexity to an application without making it faster is a waste of time.  It’s much more efficient to write 100 percent of your code to be readable, logical, and terse, then go back and speed up the 3 percent that’s actually slow.

Then he goes on to talk about ways to identify and fix the slow spots.  Many of the other authors explained how to optimize different aspects as well, which is useful information to have in mind (even if you’re optimizing for readability) because if you know which aspects can be tweaked in one direction or another, you can write those parts of the code to be as flexible as possible.

The advice about making a game fun was also enlightening.  I particularly liked Joachim Bondo’s advice on making an elegantly simple user interface (especially since this is something I’m trying to improve in my own work).  Several points left me going “That’s cool, I should do something like that…” such as the charming detail of putting a beautiful “chess engine” on the back of the chess board just to make the user smile.

Overall, I found the book entertaining as well as useful.  I just sat down and read it straight through, which I wouldn’t normally do with a computer book.

It’s been my experience that all MIDP implementations are different, but some are more different than others.  BlackBerry Java smartphones are MIDP compliant, but they have a particularly unique flavor of MIDP.  They’re also becoming increasingly popular, so I decided it was time to get one and try it out.  Here’s my new (to me, actually used) BlackBerry 8700g:

By selecting “options > about” I got the convenient info screen above, which tells me that the version is 4.1 — one of the oldest BlackBerry handsets with Java.  (That’s OK, all the better to test backwards compatibility.)

The first (and IMHO most annoying, but critical) step is to set up the development environment and get a complete “Hello World!” from code on the PC built and running on the device.  Here’s my “road to Hello World” — the problems I encountered and their solutions — in hopes of saving the next person some time:

My first step was to load a few of my simplest sample MIDlets onto the device to see if they work.  The Key Codes MIDlet worked fine — providing interesting information about which keystrokes the MIDlet can receive and which keystrokes are handled by the operating system while the MIDlet is running.  The JSR Test MIDlet also worked and provided interesting information (once I figured out that the MIDlet commands are mapped to the trackwheel and that you press in the trackwheel itself to select).  Installation was a breeze — just click on the Jar file’s URL in the browser, and the BlackBerry takes care of it.  My simplest game — the Maze game — didn’t quite work, though, so I figured the next step was to download the BlackBerry-specific development utilities.

On the BlackBerry Java Application Development Tools & Downloads page, there are two choices:  an Eclipse plugin, and a “legacy” standalone IDE.  (I found this page through the Java Application Developers page — you may need to create an account and log in to see the development tools pages.)  I assume the word “legacy” here means that they don’t intend to keep supporting it and they mean for you to switch to the Eclipse plugin.  I tried them both, and I liked the standalone IDE better.

First, the Eclipse plugin.  The spot where I wasted the most time was in trying to install the plugin into Eclipse 3.5 “Galileo”.  If you read the getting started guide, it specifically states that the plugin works in Eclipse version 3.4.  I assumed that it would also work on version 3.5 since the BlackBerry JDE Plugin for Eclipse page actually links to a download of Eclipse 3.5, and I just followed that link.  But, when trying to install the plugin, I got the following error message:

To: net.rim.eide.componentpack4.7.0 [4.7.0.46]

Cannot complete the install because one or more required items could not be found.
Software being installed: BlackBerry Component Pack 4.7.0 4.7.0.46 (net.rim.eide.feature.componentpack4.7.0.feature.group 4.7.0.46)
Missing requirement: BlackBerry JDE Plug-in for Eclipse 1.0.0.67 (net.rim.eide 1.0.0.67) requires ‘bundle org.eclipse.core.resources [3.4.0,3.5.0)’ but it could not be found
Cannot satisfy dependency:
From: BlackBerry JDE Component Package 4.7.0 4.7.0.46 (net.rim.eide.componentpack4.7.0 4.7.0.46)
To: bundle net.rim.eide 0.0.0
Cannot satisfy dependency:
From: BlackBerry Component Pack 4.7.0 4.7.0.46 (net.rim.eide.feature.componentpack4.7.0.feature.group 4.7.0.46)

It looks like the plugin required a particular set of Eclipse core resources that it couldn’t find, which is the sort of thing that smells like a version mismatch.   A little googling found me a site where I could download the Eclipse 3.4 “Ganymede” version, and the plugin installed in that Eclipse version just fine, according to the instructions in the links above.

the first drawback to the Eclipse plugin, however, is that it doesn’t appear to come with any sample code (or if it did, it’s well hidden).  For that reason alone, you might as well download the BlackBerry JDE since it comes with a big pack of sample apps.

Installing the BlackBerry JDE, building the sample apps, and running them in the simulator was pretty straight-forward.  There was one point, however, where I found the BlackBerry development environment – development guide to be a bit lacking.  I felt like it should more clearly answer the following basic questions:

1. Does the “project > build” command build the file that can be installed directly onto my device?
2. If so, where is it???

I poked around a bit, and found the built .cod files in the same folder with the source code, interestingly enough.  For the “Hello World” sample, that was “C:\Program Files\Research In Motion\BlackBerry JDE 4.1.0\samples\com\rim\samples\device\helloworld\com_rim_helloworld.cod”

Then the last step is to install it on the BlackBerry.  Fortunately, the BlackBerry JDE came with a simple little command-line utility called “JavaLoader.exe” to install applications from the PC onto the BlackBerry device.  So I connected the device via USB cable to my PC, allowed the PC to find an appropriate driver, and tried “JavaLoader -u dir” (to get the directory listing with the “-u” option indicating that I’m connecting via USB).  Unfortunately, I got this crazy message:

Error: unable to open port

Sadly, no hints as to why it couldn’t open the port, so the next stop was to search the BlackBerry developer forums.  This is the place to go — a quick search turned up the problem immediately:  you need to be running the “BlackBerry Desktop Manager” in order for the JavaLoader to find the device.  My used BlackBerry came with a couple of cables but no software, so again I turned to my old pal Google.  I tried downloading two versions of the “BlackBerry Desktop Manager” for BlackBerry 4.1 from the BlackBerry site, and — this is the weirdest part of the whole adventure — I received some entirely different program instead.  Not sure why.  But cnet.com provided a link to a version of the Desktop Manager “tested spyware free”, and that one worked.  Yay!  With that desktop manager running, JavaLoader was able to connect to the device and load com_rim_helloworld.cod onto it.

That should be the last step, right?

Sadly, no. The HelloWorld application appeared on my main BlackBerry menu, but when I launched it, it threw an Exception!  It failed to find its resource bundle!  So I opened up the source code to see what was the problem.  It turned out that it was importing packages from another sample application: “com_rim_demores.cod”.  This is just a philosophical point, but I think the “Hello World” demo should be the simplest possible application — leave the best practices about internationalization for step 2 — but that’s just me.  Anyway, with the resource demo application installed, the “Hello World” finally worked on my BlackBerry!

Now on to some actual development…

Suppose you’re writing a game or application, and you’d like it to have an attractive, professional-looking GUI (with your theme, brand, or skin), and you’d like it to run on as many Java ME MIDP devices as possible.  There’s some work to be done, but it’s not that hard.  I wrote about how to do it in the last chapter of my book, and it was the topic of my Jazoon talk.  Plus I wrote a library of utilities to simplify the task (the Frog-Parrot UI Library), but — looking over my blog the other day — it hit me that I never really posted a technical explanation of how to use this library.

Here’s the general idea:

If you want a mature product for MIDP customization — one that will teach you how MIDP customization works as you’re using it — J2ME Polish is a good place to start, as I explained here.  But in practice, I found that I wanted 100% control over the look-and-feel of the GUI, which I couldn’t get from J2ME Polish.

Essentially, handsets have a list of standard screen sizes, and many of them are so small that I need to have pixel-by-pixel control over where everything is placed.  Having the device place the widgets, etc., for you — guessing where you want them based on layout algorithms — isn’t nearly as useful on a small screen as it is on, say, a big browser window on a P.C.  So I wrote a library that would allow me to bundle the screen information into resource files, selecting the right image files for each screen size and passing along the data for how big widgets and images are and where they should be placed.

The annoying thing about making a custom GUI for MIDP is that you have to start from scratch, drawing your GUI onto a blank canvas.  That means re-inventing the wheel on some very standard functionality: widget navigation, navigating back and forth through a stack of screens, scrolling, and even cutting up a paragraph of text in the right places so it won’t disappear off the edge of the page.  That’s the functionality I’ve written for you in the FPUIL (which you can use however you like, as long as you don’t imagine it comes with a warranty. ).

In this brand-new version (which I just re-worked today on a Windows machine, download here), I’ve included some build files to build the project with Ant and Antenna. Look at the build.xml and build_all.xml files to see some examples and explanation of how to build a MIDlet for different target devices.

That should be enough to get started, and if I find some time, I’ll try to write more explanation…