Java development with an iPhone touch pad for the Atari 2600 from an urban hip-hop perspective

Tips and Tricks

**Update**
I’ve updated my example below after realizing I left out some important pieces…**Update**

How do you assert that something runs in a different thread? Or more generically, how do you assert that something runs asynchronously? I need to do this in ObjC but also in Java. The scenario is as follows. I have a WhatzItz object instance stored in myWhatzItz. I tell myWhatzItz to doDisThing. I need to specify that myWhatzItz will doDisThing asynchronously. Experience tells the story that multi-threaded unit tests are dumb, complicated and wrong. So asking myWhatzItz to doDisThing then waiting or polling for completion of doDisThing is not what we want to do here. (It may be what you want to do but it’s not what I want. Since we’re on the same team and since I’m doing the writing you have to want what I want not what you want. I want you to want my wants… forget your wants… your wants are dumb anyhow!)

So how do we design myWhatzItz to doDisThing and doDisThing right? I’m going to suggest an interface… err prototcol. That is an abstraction for what we want to design. In unit testing we stay focused on one thing. All distractions are tossed behind abstractions. So after asking myWhatzItz to doDisThing I need to assert that it uses asynchronous behavior. That brings us a step back. I have to design a dependency on asynchronous behavior first. Right now you’re probably wondering how asynchronous behavior works. Right now I’m ’bout to slap you like Bruce Lee slapped that boy in Enter the Dragon. (Or was that Return of the Dragon? Maybe it was the game of death? Bonus points to the 1st person that gets the movie correct with a link to the clip on YouTube!) “Don’t focus on the finger or you’ll miss the beauty in the sky above!”, says Bruce. We don’t care about how asynchronous behavior works, as its irrelevant to our design. We only care that our work is done asynchronously! So we’ll code this test in ObjectiveC:

Supplying the asynchronous behavior becomes a construction/intialization concern, which could be extracted into a wiring framework like Interface Builder (or if you do Java, Springframework). The nice thing is that we can alternate our asynchronous behavior without touching the rest of the project. We can do something quick/dirty like detachThread… and later get more elegant with RunLoops. Today’s tip comes to you (me) completely by accident. I’ve been trying to test drive things in Java and ObjC for several years now and I’ve never got this part quite right. Feel free to share your opinions/experiences with threads and tests.

**Update**
The above example demonstrates a few important unit testing concepts. first it uses the self-shunt pattern to allow the test to become a mock and listen for interactions between the tested object and its collaborator(s). Second, it demonstrates the importance of using tests to carve out the pieces that should NOT be under test. In this situation it’s multi-tasking, however in other scenarios it could be anything from a DBMS to a network call. I could have illustrated an example where I spin up a Thread pool of some sort from within the test started work, paused the main thread and waited for a response. That’s what I’ve done in the past and it becomes extremely complicated and brittle. In stead, I use the elegance of abstraction to make the test 100% predictable, 200% more simplistic, and 300% more maintainable. Where do I get those statistics? The short answer is they’re sequential. (The long story begins yesterday when my 5yr old spontaneously decided to count from 1 to infinity in the middle of our shopping trip. You see, she only recently learned her numbers up to 100 and after getting to 199 we all realized the child’s computational limits as she continued with one hundred one hundred then followed up with one hundred one hundred one, one hundred one hundred two…)**Update**

I wrote about SSH port forwarding a while ago but I don’t think y’all heard me. Listen up. (Place your ear within mere centimeters of your monitor if you will so that I can scream at’cha.) SECURE SHELL IS TEH BEST TOOL YOU’LL EVER USE IN YOUR ENGINEERING CAREER! I’m writing today because I was reminded from an incoming blog link about the power locked in this three letter acronym: S-S-H

By itself it doesn’t look interesting. However, if you take a minute to learn what it means, what it does, and what it can do then you’ll see why the above sentence is in all bold caps. It’s one of those things that people take for granite, like the extra buttons on your microwave. If you’re like me (and you must be or else you wouldn’t be reading) then you probably never use anything other than the “quick minute” and start buttons on the microwave. The meat/poultry, popcorn, and reheat buttons are just for show and whether they function or not is just a mystery. That’s how most people see ssh. But, but… when you learn what goes on under the acronym you start to look at those other people like fools that literally drive 747 Boeing’s to/from work and complain when they get stuck in rush hour traffic.

Let me stop right there. Have you ever had that experience before? Have you ever found out how to really use something like your TIVO or VCR, or maybe it was all the hidden features in your car like auto off lights, tire pressure monitor, and the multi-user programmable power seat adjustments. Have you later watched somebody with the same equipment literally ignore/abuse the features? Here’s the tricky part. These very same people will look at you cross eyed as you spend hours/days trying to figure out how/why feature “X” will/won’t work while they have found the shortest most abusive 30 second path to gratification. There is something to be said of folks from both camps but I’ll leave that for after post discussion if you feel like commenting. (I’m waay off topic.)

So far I’ve found at least 7-10 good uses for SSH ranging from X11 forwarding to remote port forwarding to transparent access to remote Linux-based file systems, and more. I’m certain there are many more that I haven’t found or stepped into on my way to the shed to pull out my trusty dusty mower. What way do you use SSH? Do you cut it with a 5th of gin? Have you tried it with hot sauce? Does it work well as an antacid? Maybe you’ve manage to repair that hole in your vinyl upholstery with it. Whether you’ve fixed a flat or refinanced your mortgage with it I’d love to hear your story.

Happened to me this morning. The symptoms are: launch mail, click anywhere in the windows and watch the spinning pinwheel mock you constantly… spinning and mocking you. If Mail on your Mac hangs or stops responding then here’s a 1 minute fix that may or may not work for you. Backup and delete (just drag them out of their locations to another folder or your desktop) the following:
~/Library/Mail/Envelope Index
~/Library//Caches/Mail

(The tilde “~” is shorthand for your home directory or /Users/YourUserName)

Why don’t somebody fix this already? I think I finally got the latest XCode 3.1.2 to work with the latest Subversion 1.5 release. This was after downloading the latest 2.2 iPhone SDK. I scoured the web and found the best tip here. There’s another possible more automated solution here but because I don’t feel comfortable running a bash script I copied off of some web page (try it and you’ll cuss. Then you’ll see what I mean!) I went with the other approach. I’ll shorthand the steps I followed below because following the first link above, I think, misses some important files and doesn’t work correctly. The general idea is to copy your Subversion installed libraries (assuming you used the Collab.net bundle) into the place where XCode binds to.

That’s what I did and now it no longer complains “error 155021 this Subversion client is too old and stoopid to work with your shiny new svn checkout that’s just bananas!” Your error message may vary but the concept is the same.

This message is brought to you, in part, by the proud sponsors listed in the Hall of Aim.

Such a painful problem it is to create Blackberry software from anything other than their proprietary JDE. There are options, however. There’s some blackberry Ant tools (an independent project and also there’s a few things in the Antenna project). Then there’s RIM’s rapc docs, which aren’t too informative. Finally there’s the post I made a while ago detailing some of the inner workings of rapc. In the post and also in the comments I hint at ways to get images and other resources into the final cod file. To save you the pain of reading there I’ll write about it here. Once you figure out how to compile with RAPC and at least get a working cod file, you need to compile again. The trick is to pickup the jar file that RAPC creates next to your cod and stick images and resources in there. Finally, remove some rapc generated .csi and .cso files before you pass the jar back to rapc. (If you forget to remove these files rapc will complain and list them in the error output, though you might not understand what it’s trying to tell you. Just know if you get an error recompiling jar and you see mention of a file ending in .cs-whatever that you’ll need to remove the file(s) in question.) Here’s some pseudo-code since I’m too lazy/busy/uncertain/tired/vitamin-B-deficient/loaded-with-excuses to post the real solution:

What’s really going on in rapc, Blackberry’s crazed compile tool? Let me begin by telling you that everything you’ve read until this point is not entirely accurate. There are those that will tell you that you have to run preverify.exe prior to running rapc. Then there are those who will tell you that the bb-ant-tools are sufficient. There are people that complain that the RIM compiler has bugs in it. (This may be true but I’ve so far been able to fix broken builds by using all of the advice I’m including here.) I’ve also found a blog that claims you can build from non-Windows operating systems. I’ve read in some places that either WTK or the JDE must be in the PATH so that rapc can find a preverifier. While some of these tips, tools, tutorials work they all have limits. Eventually you’ll find your application either throws random NPE’s, verification errors, or infinitely reboots the device! Now pay attention!

Now let me explain my project. I have a little bit of dependency injection going on via source generation. Then I also have some external jar dependencies. All of this creates a bit of a challenge for basic rapc invocation. In order to generate my midlet cod file I need to:

Run a source generator

Include the generated source in my list of things to compile

somehow include my external jar dependencies in the compile.

Include resources in my compiled output

Pick up my suit from the cleaners

Get the entire thing to run on my Mac?

While the last bullet is entirely optional and irrelevant, I include it because its the only way to get completely familiar with rapc. That is, if I can meet/greet/beat the challenge of cross platform compilation of Blackberry then I’ll really understand the intracacies of compiling with rapc. Now onto the juice.

How Rapc works… I think…
There are various approaches to compiling Blackberry applications that I know of.

Compile your app against the MIDP and CLDC APIs (include either WTK or MPowerplayer or someother party’s midp and CLDC jars on your bootstrap classpath for javac… making sure you use javac1.3 or below), preverify with JDE preverify.exe (found in %JDE_HOME%/bin), jar and finally compile with rapc.

Compile your application source files entirely with Rapc.

The first option has problems because there’s the possibility that javac will generate class files that will cause verification errors or (as my team discovered recently) the white screen of death when loaded onto the device. The second option has problems because it’s very tricky and prone to the same errors unless you are very dillegent. It took a lot of head banging and trial/error to come up with these details so read closely.

How do we use rapc? This is the question that still plagues me. There’s little documentation around the nuances you’ll encounter when invoking the rapc compiler from the command line. The rapc compiler is an executable (.exe) file in the JDE install directory living under the bin subfolder. First thing to note is the rapc.exe just delegates everything to rapc.jar. That means the same exact command line parameters you would use with rapc.exe will work with rapc.jar. (Call the jar with the “java -jar” command.) The most important thing to understand is that you cannot mix and match. That is you cannot use the output of javac/WTK preverify to fuel rapc. Furthermore you need to pay strict attention to the version of the JDE you use because it must be the same (or earlier) version of your target platform. For eg., if you intend to target Blackberry devices running a 4.2.2 OS you should use the compiler tools from the JDE version 4.2.2 or earlier. If you don’t pay attention to this step your product will work just fine until it’s time to ship… at which time you’ll experience weird, impossible to track/reproduce on a developer workstation, errors. There are other important tools in the JDE that you’ll need as well. The preverify tool is required (unless you’re using JDE 4.3.0 and targeting OS 4.3+) as well as the SignatureTool.jsr. Finally there is the net_rim_api.jar which lives under the lib folder in the JDE install directory. The next big thing to understand is the command line options.

import
Use the import= to specify the location of the net_rim_api.jar. This flag takes the relative or absolute path of not only the rim APIs but any other jar or cod dependencies your application has. (I haven’t tried cod dependencies but the docs say you can list cod files.) Be careful because this is only for resolving dependencies. Anything you list here will not be included in the final output cod. What this means is any jar files listed here must either be compiled as separate cod libraries or their source files somehow inlined in the final compiled. Dependencies listed here are scope as provided. In other words it is assumed they will be made available at runtime by either the RIM platform or by some pre-installed package.

codename
(codname for 4.3.0+)
This parameter threw me for a minute when I attempted to roll back to an earlier version of the RIM compile toolchain. I believe (and I need to double check and update this fact later) that rapc version 4.3.0 and higher expect a codname flag while versions prior to 4.3.0 expect a codename flag. The value you specify here will be the value used in the output codfile name. Paths can be relative to the working directory (the folder rapc is called from) or possibly absolute paths. For instance if you give build/MyApp as the value then rapc will spit all of its output into the build folder relative to the working directory giving you a final MyApp.cod file there. (you’ll also have MyApp.jar, MyApp.csi, MyApp.debug and other files in this folder.)

midlet
This is the application type. Use this flag if you plan to develop a J2ME spec compliant midlet. Blackberry support another application type, cldc, which provides RIM specific features (more on that in possibly another post) and is specified by the mutually exclusive -cldc flag. A You have to -midlet or -cldc to specify which kind of application you are building.

cldc
Use this flag if your are building a CLDC application that adheres to RIM’s proprietary launching interfaces. CLDC apps offer abilities to run in the background and be started at device boot time. There are other hidden gems here that I’d have to get into with another post.

jad
Use this parameter if you have a JAD file that includes your application’s meta data. This parameter is optional as you may substitue a .rapc file to include the meta data. Application meta data includes things like the icon to display on the desktop, the midlets contained in your aplication bundle, runtime properties, etc. Referr to the J2ME midlet spec for more detail.

rapc file
This would be the path to a “.rapc” file that includes meta data about your application. I’ll probably follow up with another post to explain the details behind this proprietary RIM spec. While a JAD file also includes meta data there are certain properties that can be included in this file that cannot be included in the JAD file and vice-versa.

class or java files
The last parameter should specify either a jar file containing the compiled classes or be a list of the .java files you intend to compile. Here’s where rapc gets really interesting. If you precompile your “.java” files you had better be certain you run the RIM preverify tool against these class files prior to invoking the compiler. Also I will repeat that you must use the same (or earlier) version preverify as your target platform. For eg., if you intend to target Blackberry devices running a 4.2.2 OS you should use both RIM’s rapc and preverify tools from the JDE version 4.2.2 or earlier. If you don’t pay attention to this step your product will work just fine until it’s time to ship… at which time you’ll experience weird, impossible to track/reproduce on a developer workstation, errors. (I said this before didn’t I?) Rapc is very picky here and the behavior varies between versions. It first calls out to javac assuming that the Java compiler is in the PATH. It then passes the output from javac to preverify. Note that in JDE 4.3.0 both “.java” source compiling and preverification is done from within the rapc.jar while earlier versions of rapc call out to the command line using the command “preverify” (not “preverify.exe”… this is an important distinction) and passing standard preverify parameters. Finally it creates the final “.cod” that will run on the device. What is included in the cod file depends on what is passed on the command line and what’s available from the working directory. For instance, your application icon (and I found this through trial and error) must be locatable from the working directory unless you specify an absolute path in the jad file. If you compile a jar file (not recommended for rapc prior to 4.3.0) then everything in that jar file (images, multimedia files, application resources, etc.) will be included in the final cod file. If you compile “.java” files directly from rapc then no application resources will make it into the final output cod file, only the compiled .class files will be there (along with the application icon specified in the jad if it can be found from the working directory). It took a lot of banging my head to figure this out. Finally instead of a jar file or space delimited list of “.java” files, you can specify a text file that lists (new line delimited style) all of the “.java” files you wish to pass to the compiler. This is a potential work-around to command line size restrictions that may be present on some versions of Windows. This file should be given with an @ prefix. For eg. if your have a MyApp.txt file then the last parameter for rapc will be @MyApp.txt. This is the preferred method of giving files to rapc because as your application grows so will the list of files.

One last got’cha I found was with trying to use rapc.jar directly instead of rapc.exe. If you are running a JDE earlier than 4.3.0 then you’ll get into trouble here because there is a secret parameter passed from rapc.exe that RIM won’t tell me about. Because the command line syntax for the jar is identical to the command line syntax for the “.exe” you can almost get away with it but because of a secret exchange happening between the Jar and exe you’ll get undefined behavior and weird errors in certain circumstances. This last gotcha is what makes it impossible to compile on an OS other than Windows while targeting a RIM OS earlier than 4.3.0.

In the end I’ve determined that it is not possible to accurately build a blackberry application on an operating system other than Windows. Also while there may be some truth to the myth of bugs in rapc I believe it all boils down to a bunch of nasty assumptions the RIM developers made during the design. (they assumed everyone would be so thrilled with their Swing based IDE that they would throw away Eclipse/Idea/Netbeans and burn their Macintosh laptops in celbration of the obviously superior RIM tool chain.) I do believe that if you pay close attention to the details outlined above you can diagnose most preverification and random erros you may be suffering from. I plan to revist this topic in the future as I’ve taken a break from mobile and begun work on some other things. However I do not plan to let rapc defeat me entirely. Keep an eye out because I’ll likely be updating this very same post with more details.

I got a lot to say but no time to say it. For now just know that I’m back on Linux and fighting with audio incompatibility. It sux because most everything else works on my fresh new Mint Linux (that’s right I’m on Mint now, not Mepis, not Kubuntu…) install. For what it’s worth I think my answers may be here. If you have a Creative Sound Blaster X Fi card and are considering installing the latest version of Mepis, (K)Ubuntu, or Mint, look at this guide: http://ubuntuforums.org/showpost.php?p=4823915&postcount=675

There’s a blurb about SLAB vs. SLUB don’t ask me what it means just follow along. I’m going to try this myself in another day or so.