Presently, we have two supported options for developing Blackberry projects: use the RIM JDE (if you’ve tried to use it, you know that this isn’t an option at all); or use their Eclipse/JDE plugin.  Outside of that, you’re pretty much on your own.

I’m a long-time Netbeans fan — I’ve tried Eclipse multiple times, and I just don’t get along with it.  With a bit of headache and digging, I’ve been able to get most BB development tasks working in Netbeans.   Until this week…

In working on BBSSH, I realized that people may eventually want translations, so I set out to use the provided localization features of the Blackberry platform. (Also, all those raw GUI-related strings in my code were annoying me.) Unfortunately, because I don’t fall into the “JDE” or “Eclipse” categories mentioned above, I fell into the third: pretty much on my own.  In hopes of preventing the next person who attempts this from falling into the same category, I figured I would write up how I worked this.  Note that this isn’t necessarily the best or the only way – but it does work, and it does not add a lot of pain to the process.

This tutorial assumes you are familiar with Netbeans, and have some familiarity with the JDE. Read on for more. For the impatient, you can skip straight down to “3. The solution”.

1. Some Background (skip this if you’re familiar with how BB localization bundles work)

When you create a localization bundle in the JDE, it does some behind-the-scenes work that allow you to start using it right away.  Let’s say you created files named “MyApp.rrc” and “MyApp.rrh”.  Behind the scenes, JDE will create a file named MyAppResource.java, compile it, and add it as a resource to your project.   (Also important but less relevant here, it will also generate a binary file containing the actual string data.) The java file MyAppResource.java is a simple interface – here is an excerpt from BBSSH:

package net.uglydesign.bbssh.i18n;

public interface BBSSHResource {
 // Hash of: "net.uglydesign.bbssh.i18n.BBSSHResource".
 long BUNDLE_ID = 0xe8304654750e8634L;
 String BUNDLE_NAME = "net.uglydesign.bbssh.i18n.BBSSHR";

 int MENU_EDIT = 12;
 int INFO_SETTINGS_GENERATING_KEYPAIR = 35;
// snip
}

Those int values map to the string table, allowing you to look the value up at runtime using the appropriate ResourceBundle instance.   You would either reference this new interface directly, or implement it in your class to get direct access to the key values.  For example:

public final class SessionDetailScreen extends MainScreen implements BBSSHResource {
 private final SessionProperties prop;
 ResourceBundleFamily res = ResourceBundleFamily.getBundle(BUNDLE_ID, BUNDLE_NAME);
 // snip //
 private final String[] CONNECT_CHOICES = res.getStringArray(SESSION_DTL_LIST_CONNECT_CHOICES);
 // snip // 

 SessionDetailScreen(SessionProperties prop) {
     super(Screen.DEFAULT_CLOSE);
     this.prop = prop;
     if (prop.isNew()) {
         setTitle(res.getString(SESSION_DTL_TITLE_1));
     } else {
        setTitle(res.getString(SESSION_DTL_TITLE_2));
 }

The text in bold is  made available to your class when you implement the by the BBSSHResource interface. Implementing this interface is a convenience to save you a bit of typing. You could just as easily do this:

public final class SessionDetailScreen extends MainScreen {
 private final SessionProperties prop;
 ResourceBundleFamily res = ResourceBundleFamily.getBundle(BBSSHResource.BUNDLE_ID,
     BBSSHResource.BUNDLE_NAME);
// snip //private final String[] CONNECT_CHOICES =
res.getStringArray(BBSSHResource.SESSION_DTL_LIST_CONNECT_CHOICES);

2. The Problem

As long as you’re in the JDE or Eclipse environment, the creation of this interface is completely transparent to you.   Once you step outside of that realm, troubles begin.  As it turns out, the java interface file is created in a temporary folder, and is usually deleted shortly after it is created – giving it a lifespan of a few seconds in many cases.  The Eclipse plugin then performs some hidden internal magic to add the compiled version of that file to the Eclipse project, making it available for you to use.

I spent far too much time trying to find a way to get my Netbeans project to recognize this generated class, with no luck.  The details aren’t relevant here, but I lost about two days trying to force some the appropriate level of cooperation between RAPC and Netbeans before giving up.  My attempts yielded run-time errors or build-time errors, depending on what I was trying at a given moment.

Posting to the Blackberry development forums yielded people willing to help, but the suggestions provided did not seem to do this trick.  (Note that this could be my fault entirely, so no fault to the posters there )   Google trawling turned up a lot of references to someone who had solved this exact problem a couple of years ago — Jonathan Fisher.  Unfortunately, he has taken all of his Blackberry-related content off of his web site , so the net result was a bunch of dead links.

3. The Solution

This seemed to narrow it down to two remaining options: implement my own resource parser (possible, but pointless work – I shouldn’t have to when Blackberry already has a perfectly good one), or find a way to have a separate project that contains only localization resources.   The latter is the path that I took, and what I’ll be describing here.

Create a Resource-only project

First we need to use the JDE to create a project.  The only thing contained in this project will be our localization resources.  Note: at your discretion you may also add other resources such as graphics, but this is not covered here.

1. Using the JDE, create a new workspace such as “YourProjectName” in a new folder named “JDE” under the project root.
   • The location you choose to create this workspace is ultimately up to you.  However, I would strongly recommend creating this project under a new folder located in your main project, such as in “/JDE” as described. It will generate a lot of clutter if you keep it at the project top level; while moving it to a new directory outside of your project folder just means that you will have to remember to check out an additional set of files before you can build/test.
   • Do not put any files from this new project anywhere under your Netbeans “YourProjectName/src” directory.  Doing so will cause further complications that I will not be addressing here. (I know this because I went that route first )
2. Using the JDE, create a new project within the workspace, called “YourProjectNameResources”
   • You should probably put this in the same folder you used for the workspace.
3. Designate the project as a Library.
   • Right-click on the project name and choose Properties.
   • Click the Application tab
   • Change the project type from “CLDC Application” to “Library”.
   • You’ll probably also want to take this opportunity to set a version string, vendor, and description so that when someone sees this installed as a module on their BB, they will know what it’s for.
4. In the JDE, create your resource header yourproject.rrh and resource content yourproject.rrc files.
   • When prompted for a package name after creating the RRH file,  make sure to update it.  For example, most of BBSSH’s content is under “net.uglydesign.bbssh”, so I specified “net.uglydesign.bbssh.i18n” for localization resources.  This is the package that your Resource interface class will be created under.
   • More details on how to create these files and their significance can be found in the official BB localization tutorial.
5. Add some strings in the resource editor to get started.
6. Build your project in the JDE by right-clicking the project name and choosing “build”
   • Ignore the warning about no main() function
   • Upon completion, you’ll now see a bunch of files in your “JDE” folder. The one that we care about is called yourproject.jar (or in my case, BBSSHResources.jar).

Add the JAR file to Netbeans.

Now we have to make sure Netbeans is aware of our new dependency, so we’ll add the jar file created by the previous step to this

1. On the Projects tab, right-click on the Resources heading and choose “Add jar/zip…”
2. Find your way to the .jar file created by the JDE — if you followed above, you should find this in /JDE/YourProjectNameResources.jar.

You’re done!

Netbeans takes care of the rest, ensuring that the new JAR file is included in the RAPC compilation.

Adding new strings is now very straightforward.  The only downside is that you’ll need to keep the JDE running in the background.  To add string resources:

1. Alt-tab over to the JDE and add them via the resource editor.
2. Build the resource project.
3. Return to Netbeans and begin using the new resource constants immediately. Netbeans will (after a second or two) pick up the updates automatically.

4. Some Notes

That aside, there is room for improvement in what I detailed above….

1. Thee generated resource .jar file also contains the COD file for the resource library; by extension this means that the actual binary resources are also getting packaged in your main application COD files.  This is redundant and takes up extra space.  I’ll post back on this when I update it properly (Likely sometime around when BBSSH is in public beta.)  I think the proper solution will be:
   • Modify project build.xml to clean the JAR file when creating a deployment: remove everything except the  interface class file.
   • Modify project build.xml to update the JAD and ALX files, indicating the new resources COD as a dependency.
2. The JDE can be avoided by using RAPC directly to compile your RRH/RRC files into a COD. You can run this from any location, allowing you to remove the output clutter.  This would let you just create a new build target in build.xml, and do your resource builds from inside of Netbeans while you work.   The only drawback to that is that string editing is going to be painful if you’re not using a GUI resource editor.  It is possible (rrc/rrh are just text files after all), but after going that route myself I found it easier to just switch back and forth between the JDE and Netbeans for string editing. Maybe one day I’ll get around to a standalone editor – or maybe RIM will open source their Eclipse plugin which contains a good editor -  but for now this suffices.
3. It has to be possible to have the main application COD reference the resource COD to provide title and description data. I haven’t looked into this yet, but I suspect this will require using a “rapc” configuration file specific to this project.

5. I’ll shut up now

I’ll continue to hope that one day RIM will realize that there really is a need to provide better tools for managing this.  Android and iPhone have great development toolchains, and Blackberry’s lack of one can only hurt it.   In the mean time, even though this is not ideal it suits me well and does the job. Hopefully it will do the same for you.

Please post a comment here to let me know if this helped you, or if you have other feedback, questions, or concerns.

Separately, I’ve also been toying with entering the under-served BB games market with an idea I’ve been fermenting in the back of my head.  In order to pull that off, I needed to have real-world experience with BB platform development. I took a close look at my most-used app (MidpSSH) and saw  again that it could become a lot more powerful if it was built in a way that allowed it to take full advantage of the blackberry-specific features.

With a recent update to BB os 4.6, my backspace key stopped working in midpSSH – and that was the proverbial back-breaking straw.   I steeled myself and dove in. I decided that I would go “whole hog” — I would  make a Blackberry-specific variant of midpssh, eliminating the support for non-BB phones, taking advantage of the features BB has to offer programmers – and adding new features and usability tweaks along the way. I would keep the core functionality of the original (terminal emulation and SSH*/telnet layers) but rewrite the rest using BB APIs. In keeping with the spirit of the original name, this project will be called “BBSSH”.

Because this is a pretty drastic set of changes – practically a rewrite save a subset of core classes -  I have forked the original code, which is still available via Karl’s site and Sourceforge.     The new code will also be released under GPLv2, and will be published once the first beta OTA download is available. I contacted Karl ahead of time, and he was friendly and supportive of the idea. While he does not have time to maintain MidpSSH any more, he has been  (and continues to be) helpful in providing me with information I need to make the project go from my end.

Which brings us to the present.  Over the last month or so, I’ve been working on this conversion and learning a lot about the BB platform along the way**.  It has been in some ways less difficult than I expected, but in other ways more so. Information about development for the BB is scattered with little central organization.  Tidbits here, chunks there. RIM is working hard to resolve this, but I think they still have a ways to go before they’re there.    Much of the information I needed is in RIM KB articles – but I wasn’t able to find much in there on my own.  (Frankly I think it’s because they’re using livelink – a document management solution which has been pretty horrible for the ten years I’ve been stuck using it..)   Instead, I stumbled across or was directed to them from old forum postings in various places, Stackoverflow answers, and helpful replies to my inquiries on the RIM Blackberry dev forums.

Lunch is almost over, so I have to get back to work .  I have time for some screenshot uploads which I’ll be posting separately in a moment.  Later today, I’ll be adding a features roadmap post.

* I am also looking at the Blackberry crypto layer – it may be possible that I can replace the SSh layer with this for the most part. THat’s still up in the air though – as it may require additional licensing/code-signing fees beyond the basic $30 BB signing fee — which isn’t high on my list of things to do.

**Among other things, I”ll be posting project updates here (tag: bbssh) , but I will also be journaling my experiences as I develop my first “real world” BB application (tag: blackberry-dev).  This is information that I’ve been uncovering from a dozen or more different sources, piecemeal. It would have helped me a lot to have one place to find the information, and it will help me in the future when I start my next app — and hopefully by publishing it I can also save someone else the headache I went through.