12-07 14:42:52.722 E/AndroidRuntime(18421): FATAL EXCEPTION: main
12-07 14:42:52.722 E/AndroidRuntime(18421): java.lang.NullPointerException
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at android.app.LoadedApk$ServiceDispatcher.doConnected(LoadedApk.java:1064)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at android.app.LoadedApk$ServiceDispatcher$RunConnection.run(LoadedApk.java:1081)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at android.os.Handler.handleCallback(Handler.java:587)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at android.os.Handler.dispatchMessage(Handler.java:92)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at android.os.Looper.loop(Looper.java:130)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at android.app.ActivityThread.main(ActivityThread.java:3701)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at java.lang.reflect.Method.invokeNative(Native Method)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at java.lang.reflect.Method.invoke(Method.java:507)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at com.android.internal.os.ZygoteInit$MethodAndArgsCaller.run(ZygoteInit.java:866)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:624)
12-07 14:42:52.722 E/AndroidRuntime(18421): 	at dalvik.system.NativeStart.main(Native Method)

I fretted. I winced. I even felt a slight irritation coming on.

The Solution
In the end I found out the reason behind the mysterious NullPointerException. My application is binding to a Service and it turns out that the ContextWrapper.bindService()-method can't take a null as its ServiceConnection parameter.

ContextWrapper.bindService():
public boolean bindService (Intent service, ServiceConnection conn, int flags)
Connect to an application service, creating it if needed.

Instead of throwing a helpful IllegalArgumentException it forwards the erroneous null-parameter into the innards of The Android Service Beast. That part is then unable to use it and throws a NullPointerException instead together with its own stacktrace which your code is not a part of.

The Summary
In short, make sure you don't pass bindService() a null as the ServiceConnection parameter or you will get an unknown NullPointerException which is hard to track down.

The Current State of Affairs

Most Open Source projects for iOS are distributed as a source code repository with an Xcode project. But here the good news stop for most projects. The Xcode project usually only has one target, a sample project, mixing the reusable code in the same bucket as the sample/incubator code around it.

The usage instructions suggest you drag and drop a directory, or even worse a collection of files, into your own project. This is a very primitive solution, passable in the '80s when all we had was disks and BBS:es, not good enough today. All history and connection back to the source is lost, any value added by source control systems is lost the second you decide to use an open source component this way. Any bug-fix or improvement you make will require a manual merge back to the original project. You also loose all tracking information the moment you copy a file, what version of project X did you use, some special branch?

This Need To Change

This affair also highly discourages re-use. Almost every open source project out there that involves network connectivity also uses Apple's Reachability example code as a base for determining network status. Apple's code is not complete for all use-cases, and not free of bugs, so almost every project has a more or less modified variant of the same code causing compiler errors. Ensuring that using several open source project in one application is bound to end up with conflicts. Leaving it up to you to determine which projects version of Reachability that is the master version, often you end up writing a third version of Reachability for your project. And none of these changes and improvements will ever end up in a re-usable way for the iOS community as a whole.

This is not an impossible problem to solve, in the Java world there is for example Maven that solves this very well. Maven is a huge tool, and re-inventing that wheel for iOS would be a mammoth task. Fortunately that is not needed; Xcode already has the basics that we need in order to create iOS projects that are highly extendable and re-usable.

There is a Solution Today

One Xcode project can have one or more targets, usually the target is your application, sometimes you have one target for iPhone and a separate target for iPad. Targets are not limited to applications, you can also have a Unit-test targets, and more importantly static library targets.

A static library target yield a static library that can be linked into any other target, so be applications or other static libraries. A static library is a cruder version of a Framework, like UIKit and Core Data that Apple provide us. Crude as they are, it is still good enough to use for sharing re-usable Open Source project components.

A Xcode project has the notion of sub-projects. A Xcode sub-project is a reference to another Xcode project. You can set the sub-project's Targets as direct dependencies for your targets, and instruct the sub-projects products to be linked with your products. In essence say "Use what that other Xcode project creates to build my project".

The idea of Xcode's sub-projects has a logical one-on-one mapping to sub-modules in Git. Meaning that exposing re-usable iOS Open Source projects as static libraries on for example github is as easy as can be.

Eating Your Own Dogfood

This is actually what I have done for years, ever since I released HessianKit in 2008. Most of the code you write will be re-usable for the next project, having an easy way group your re-usable components into a growing library will save you a lot of work.

Firstly I never have to start with a blank canvas for any project. But more importantly, when working on many applications, any bug fixes and improvements I make to my shared components immediately trickles out to all other projects as well. If I add animated insert of cells in my column table view for project A, then all other projects is only one git pull away from benefiting from this new feature as well.

Jayway have since a few weeks begun the process of publishing our re-usable components for iOS. So far this has resulted in three projects on github:

• CWFoundation - a collection of new classes and categories to add functionality that is commonly missing from Foundation framework.
• CWUIKit - a collection of classes and categories that do the same for UIKit. CWUIKit requires CWFoundation.
• CWCoreData - A collection of categories for Core Data that makes using Core Data in a multithreaded application a breeze.

These are living projects and will be updated with new functionally over time, and large enough to warrant a blog-post for each on their own. There are also a few Componentized forks of popular iOS open source projects at Jayway's github page.

Tutorial for Using a Sub-Project from a Sub-Module

Working with an environment like this have many benefits, but also requires some knowledge of both Xcode and git. There are a few gotchas to be aware of, limitation of Xcode and the linker, best explained with a short tuturial.

CWUIKit has additions to UIAlertView that allows an alert to be created directly from a NSError instance, just like AppKit do on Mac OS X. Lets walk through how to create a new project that uses this functionality from CWUIKit to display the error message from a faulty URL request.

This tutorial is for Xcode 3.2, but works with minor modifications for Xcode 4. Changes for Xcode 4 are written in block quotes like this.

1. Create new "Window-based Application" from Xcode.

I chose a Window-based app because it contains the least amount of template code, and fits the purpose of an example well.

2. Initialize the project directory as a git repo.

git init

We need to initialize the project directory as a proper git-repo in order to use git's sub-modules.

Skip this step if project is created with git-repo in Xcode 4.

3. Add sub-module

git submodule add git@github.com:jayway/CWUIKit.git Components/CWUIKit

This will create a sub directory named Components, this is where I by convention put all my sub-modules/sub-projects, it is not a hard requirement.

4. Update and initialize all submodules

git submodule update --init --recursive

A git-submodule is by default not initialized, this is to avoid downloading large amount of data for a sub-modules you do not need, such as a test project. This is why we must update and initialize the sub-projects to realize them when starting a new repo or cloning an old one.

5. Add sub-project

Locate CWUIKit.xcodeproj and drag and drop into your project.
Highlight the CWUIKit.xcodeproj item and ensure the "Target Membership" column, that has a bullet as symbol, is checked for the libCWUIKit.a product. This is the static library to link against.
Also add the CWUIKit target as a direct dependency to your applications target so that CWUIKit is automatically build before building your application.

It is not required to setup target membership in Xcode 4, only set Target as Target Dependency in Build Phases tab, and add the Product to be linked in the same tab.

6. Recursive Sub-Projects

Static libraries are by their nature linked into your binary, this means that if static lib A and static lib B both define the same global symbol C you will get a duplicate symbol ‘C’ error when linking you app.
CWUIKit uses functionality from CWFoundation, but because of this limitation of the linker it can not explicitly add this functionality to itself. Doing so would make it impossible to use CWUIKit side-by-side with other projects that also uses CWFoundation, such as CWCoreData.
The work around is that any project that includes CWUIKit must also include CWFoundation. So repeat step 5 with the CWFoundation.xcodeproj from /Components/CWUIKit/Components/CWFoundation.

Xcode 4 has full knowledge of recursive sub-projects, so this step can be skipped. Only add CWFoundation sub-projects product to be linked.

7. Add QuartzCore and OpenGLES frameworks to your target.

Static libraries can not enforce linking of frameworks on it’s own, so building the app in it’s current state would result in missing symbols errors.
Using CWUIKit requires the app to be linked against QuartzCore and OpenGLES frameworks for CoreAnimation and OpenGL additions.

8. Setup header search paths.

Unfortunately sub-projects headers are not automatically added to the search path of your projects. So you must add "Components/**" as a header search path for your project.

Xcode 4 considers header search baths to be an advanced setting, to change the build settings display for Basic to All if you can not find it.

9. Setup linker flags

Add "-all_load" to other linker flags.
The GCC and LLVM linker also has a limitation/bug for static libraries that will strip out any methods for categories on a class that is not defined in the static library. For example any method extending UIAlertView in libCWUIKit.a will be stripped out by this bug.

10. Add #import "CWUIKit.h" to you application delegate. And add this small code to the application:didFinishLaunchingWithOptions: method

NSError* error = nil;
[NSData dataWithContentsOfFile:@"wrong path!"
                       options:nil
                         error:&error];
[[UIAlertView alertViewWithError:error] show];

11. There is no step 11.

But there is a screenshot of the running app.

Conclusions

This method of using Xcode sub-projects and git sub-modules for managing shared components works very well, and scales to be even better the more sub-projects and developers you have. The greatest benefit is without any doubt that bug-fixes and new features by default always trickles back to their source and become re-usable for all.

All the downsides are in the limitations of static libraries themselves, and can unfortunately not be overcome unless Apple introduces proper support for third party frameworks in iOS SDK. The two major gotchas are missing symbols caused by missing frameworks required by dependencies, and duplicate symbols caused by implicit inclusion of dependencies from dependencies. I have found that the best solution is to always have a README with your project where you explicitly name each Framework and Component that is required.

Using Xcode sub-project to manage your builds solves the problem of dependency resolution without the need to write a new system, works on the developer's desktop as well as on a build server. Using git sub-modules to manage your dependencies solves the problem of including all recursive dependencies as well as versioning. Any sub-module can by locked at a particular stable version by commit or tag as required, with full history. But best of all; you as a developer is free to just code away knowing that you can later commit and push your changes back, independently of how or where the code originates.

Design and performance over architecture and frameworks

We have to focus our attention on the user experience, how the application is perceived and not what technology is used or how the application is built. The important thing is that the application is well designed and that it responds to the user. SO to be a WP7 developer there are two things you really have to study, and study hard:

Design
Performance

We're not suggesting that you throw out all the knowledge around architecture and framework. But, if it impacts design and performance you should think twice about why. Also, as Johan Lindfors said in his session – “stop building frameworks! Start building applications”

Slides and samples

Anyway, to sum this up we share the slides on slideshare as well as provide the code and slides as files below.

Windows Phone 7 in blend and code – code
Windows Phone 7 in blend and code - slides

Resources

Following is a collection of useful links to get started with real development - just promise you don’t build another framework.

• The UI and interaction guideline for Windows Phone 7
• Jeff Wilcox designer guideline for developers
• Peter Torr’s memory profiler
• Silverlight Toolkit
• LowProfileImageLoader by David Anson
• DeferredLoadContentControl by Colin Eberhardt
• Peter Torr’s LazyListBox
• Gif decoder as part of the ImageTools for silverlight

Be creative! // Andreas Hammar & Håkan Reis

My friend and colleague Christian Hedin gave me tips on iCuke. Cucumber has been widely used for testing web applications, but now it’s also possible to test iOS (iPhone and iPad) apps with help of the iCuke library (https://github.com/unboxed/icuke). iCuke uses AppleScript to drive XCode in order to launch your application into the iOS Simulator. A preloaded library is used to inject a small HTTP server into your application. The HTTP server allows you to see an XML representation of the iOS device screen and to emulate input, such as taps, swipes and pinch gestures.

You can read more about it here:
http://www.unboxedconsulting.com/blog/cucumber-iphone-icuke
http://pragprog.com/magazines/2010-07/bdd-on-iphone-icuke

Really excited about Cucumber on iPhone we decided to give it a try. After installing iCuke and doing some test runs it was clear that some challenges had to be overcome to make this a truly useful tool for Behaviour Driven Development and automated testing of iOS apps.

Challenge 1: Screen returns the previous screen's xml

In our test, we wanted to tap a button, come to another screen and expected to see a text. When the test runs the iPhone is driven to the correct screen, e can see the expected text but the test fails anyway. After little debugging we realized that the method screen.xml returns old xml directly after changing the screen.

Solution:

We needed to refresh screen before checking if the expected text is on the new screen. iCuke has a method to refresh screen but it is private and we could not use it. So we just added a new method to the existing ICukeWorld class.

class ICukeWorld
 def refresh_screen
   refresh
   screen
 end
end

Calling this method before checking for the presence of the text solved this problem.

Later on, I forked iCuke and added this and some other methods.

git://github.com/DavorC/icuke.git

Challenge 2: Timing

Everybody knows that using sleep and delays in code is not so flexible.

sleep 3 # wait 3 seconds

We want to check something on the screen and give it 3 seconds to finish its loading.

Is it enough? Maybe, maybe not. Screen content loading could take 0.1 second or 5 seconds or... - You know what I mean.

In the first case loading is finished quickly and we unnecessarily spend 3 seconds for doing nothing . If we have a lot of delays in our code then our tests would waste a lot of precious time.

In the second case the delay is not long enough and the test fails.

Solution:

We need to write some help functions to wait for different items which are expected: some text, a button, downloading spinner etc.

Example with wait for text:

def wait_for_text(text, timeout = @@timeout)
 puts "#{method_name}(#{text}, #{timeout})" if @@debug
 refresh_screen
 start_time = Time.now
 until(screen.exists?(text)) do
   if Time.now - start_time > timeout
     flunk("#{method_name}: Timed out after #{timeout} seconds")
   end
   sleep 0.1
   refresh_screen
 end
end

As you can see the method is waiting for the text to appear and does checking every 0.1 second. As soon as the text is found the test continues. If, after given timeout, the text is still not found, the test fails.

I prefer to use unit test assertions in my tests (flunk is an assert which always fails). To use assertions with cucumber you need to add assertions to the Cucumber World:

require 'test/unit/assertions'
World(Test::Unit::Assertions)

Challenge 3: Different tappable object on screen can have the same text label.

Identifying objects on the screen only by text is not enough. By default, the first tappable object is tapped. What if we want to tap the second one?

Solution:

I created a set of help functions for:

returning all objects that satisfy some criteria
returning a specific object
waiting for a specific object
checking if a specific object exists

Objects are described in xml by: type, label, traits and index.

Here is an example of getting an array of all elements satisfying given attribute values.

def get_all_elements_by_type_label_and_traits(type, label, traits)
 puts "#{method_name}(#{type}, #{label}, #{traits})" if @@debug
 refresh_screen
 doc = REXML::Document.new(screen.xml.to_s)
 elements = REXML::XPath.match(doc, "//#{type}[@label=#{label.inspect}][@traits=#{traits.inspect}]")
 elements
end

Observe how it is easy to parse xml using ruby's REXML library.

Of course I could write more generic methods and decrease number of code lines - something like:

get_all_elements(type, options = {})

but I like readability so I wrote a set of help functions with more specific naming:

get_element_by_type(type, index = 0)
get_element_by_type_and_label(type, label, index = 0)
get_element_by_type_and_traits(type, traits, index = 0)
get_element_by_type_label_and_traits(type, label, traits, index = 0)
get_all_elements_by_type(type)
get_all_elements_by_type_and_label(type, label)
get_all_elements_by_type_and_traits(type, traits)
get_all_elements_by_type_label_and_traits(type, label, traits)
get_all_static_texts()
get_all_labels_by_type(type)
get_all_labels_by_traits(traits)
element_by_type_exists?(type, index = 0)
element_by_type_and_label_exists?(type, label, index = 0)
element_by_type_and_traits_exists?(type, traits, index = 0)
element_by_type_label_and_traits_exists?(type, label, traits, index = 0)
text_exists?(text)
wait_for_element_by_type(type, index = 0, timeout = @@timeout)
wait_for_element_by_type_and_label(type, label, index = 0, timeout = @@timeout)
wait_for_element_by_type_and_traits(type, traits, index = 0, timeout = @@timeout)
wait_for_element_by_type_label_and_traits(type, label, traits, index = 0, timeout = @@timeout)
wait_for_text(text, timeout = @@timeout)
get_center_of_the_element(element)
tap_coordinates(x, y)
double_tap_coordinates(x, y)
tap_element(element)
double_tap_element(element)
tap_text(text)
double_tap_text(text)

In order to use these functions you need to use iCuke from:

git://github.com/DavorC/icuke.git

Don't forget to use –recursive flag when you clone it:

git clone --recursive git://github.com/DavorC/icuke.git

After building and installing the iCuke gem you need to

require 'icuke/cucumber_ext'

instead of:

require 'icuke/cucumber'

Example of usage

In your feature-file:

Background:
 Given "myApp.xcodeproj" is loaded in the simulator

Scenario Outline: User try to login with different invalid credentials with valid signs
 When I am in "Account" section
  And I paste in username "<user>"
  And I paste in password "<pass>"
  And I tap Login button
 Then I will see alert dialog

 Examples:
 | user            | pass      |
 | test@test.com   | test      |
 | 123456          | qwertyui  |
 | ..@..com        | . . . €<> |

step definitions:

When /I am in "(.*)" section/ do |section|
 wait_for_text(section)
 tap(section)
 wait_for_element_by_type_and_label("UINavigationItemView", section)
end

When /I paste in username "(.*)"/ do |user|
 label = "E-mail"
 refresh_screen
 assert(get_all_static_texts().include?(label), "No text field with label #{label} was found")
 write_to_mac_clipboard(user)
 paste_clipboard_to_text_field("UITextFieldLabel", label)
end

When "I tap Login button" do
 wait_for_text("Login")
 tap("Login")
 wait_for_download_indicator_finish
end

Then "I will see alert dialog" do
 wait_for_element_by_type("UIAlertView")
end

Testing both iPhone and iPad
If you’re testing a universal app that runs on both iPhone and iPad I recommend writing different scenarios for the platforms. iPad in landscape mode is most likely to reuse most of code you have written for iPhone. Place them in different feature files and tag them with e.g. @iphone respective @ipad tags.

In your env.rb file:

$PLATFORM = "iphone"

Before('@ipad') do
 $PLATFORM = "ipad"
end

Before('@iphone') do
 $PLATFORM = "iphone"
end

Use in your feature files:

Given I have started application

Implementation:

Given "I have started the application" do
 # ... some code
 Given "\"myApp\" from \"myApp.xcodeproj\" is loaded in the #{$PLATFORM} simulator"
 # ... more code
end

If you wants to run iPad simulator in landscape mode:

def switch_ipad_to_landscape
 if(get_ipad_orientation == PORTRAIT)
   rotate_simulator_left
 end
end

where get_ipad_orientation is some application specific method to decide if the simulator is in portrait or landscape mode.

Running iCuke tests on Hudson server

It’s really nice to be able to run your test suite at given intervals, or when you commit to the source code repository. To run your iCuke tests on Hudson (which is a popular continuous integration build server) you must start your iPhone simulator from a terminal window. This is easiest to do by launching an AppleScript from Hudson.

Below are two scripts, one AppleScript and one shell script, that I used to run my iCuke tests from Hudson.

- run_cuke.scpt

-- run_cuke.scpt
tell application "Finder"
 set my_folder_path to container of (path to me) as text
 set posixPath to POSIX path of file my_folder_path
 set scriptPath to posixPath & "cuke.sh"
end tell
tell application "Terminal"
 activate
 do script scriptPath
end tell
delay 1200 -- it should be enough to finish all tests
set logscript to "grep -c FAILED " & posixPath & "cuke.log" & " | cat"
set cuke_failed to do shell script logscript
if cuke_failed > 0 then
 error "Cucumber tests failed"
end if
try -- do not leave terminals after test run
 do shell script "killall 'Terminal'"
end try

- cuke.sh

#!/bin/bash
scriptpath=$(cd ${0%/*} && echo $PWD/${0##*/})
SCRIPTFOLDER=`dirname "$scriptpath"`
echo Cucumber script is run in: $SCRIPTFOLDER
cd $SCRIPTFOLDER
cucumber $SCRIPTFOLDER/features --format=html --out $SCRIPTFOLDER/cuke_results.html > $SCRIPTFOLDER/cuke.log

Add these two scripts to your project.
Then, add this Cucumber hook to your env.rb file:

After do |s|
 if(s.failed?)
   puts "Scenario FAILED: <#{s.name}>"
   puts "More info about failure: SCREEN XML"
   puts screen.xml
 else
   puts "Scenario PASS: <#{s.name}>"
 end
end

On Hudson, create a new job and copy the configuration from your project's existing job.
Configure job:
add to description:

<a href="/hudson/job/Helios_Cuke/ws/cuke_results.html">Cucumber Results</a>
<b> | </b>
<a href="/hudson/job/Helios_Cuke/ws/cuke.log">Debug.log</a>

add build step (execute shell):

osascript ${WORKSPACE}/run_cuke.scpt

Of course you can change all scripts according your needs.
At the end you should have your iCuke tests running on Hudson and you will get both a nice test report in HTML and the debug output as a plain text.
There is a lot of potential for doing automated feature tests for iOS using Cucumber and with iCuke and the additions above you’ll hopefully be well on your way for doing BDD in your next iOS project!

NSOperation do not have any facilities for returning a result when done as the Future do, you are left to implement this on your own. Which I have done a few times, and as a rule of thumb, make the solution generic when needed for the third time.

Operations works perfectly for background network activities. One common network activity is search-as-you-type, in this case you need to also cancel the previous operation if it has not yet been completed, so lets built this behavior into the generic solution as well.

API Design

What we want is an subclass of NSOperation that provides a future result, lets call this class CWFutureOperation. It is abstract, so users are supposed to subclass and implement main method just as for NSOperation, only difference is that the main method implementation must call setResult: before exiting.

The result that is set in the main method implementation can then be fetched using the blocking method result, equivalent to get() from the Java Future. As an alternative we would also like to be handed the method upon completion via a target-action pair. If the target-action pair is only called for finished operations that are not cancelled, then we get the search-as-you-type behavior for free.

It is also nice to be able to wrap up any method returning an object in a future operation as a convenience, so lets add that as well to our class interface:

@interface CWFutureOperation : NSOperation {
@private
    id _result;
    BOOL _isResultSet;
    id _completionTarget;
    SEL _completionSelector;
}

-(id)result;
-(void)setCompletionTarget:(id)target selector:(SEL)selector;
-(void)setResult:(id)result;

+(CWFutureOperation*)operationWithTarget:(id)target
                                selector:(SEL)selector
                                  object:(id)object;

+(CWFutureOperation*)operationWithInvocation:(NSInvocation*)invocation;

@end

Implementation

The client of the code must be able to fetch the result and the CWFutureOperation subclass must be able to set the result. The result method should block until the operation is finished if needed, and must properly return a result that can survive the operation that might be in a release pool. The implementation for this is straight forward, only minor complexity added in order to allow the result to be set multiple times:

-(id)result;
{
    if (![self isFinished]) {
        [self waitUntilFinished];
    }
    if ([self isCancelled]) {
        return nil;
    }
    return [[_result retain] autorelease];
}

-(void)setResult:(id)result;
{
    _isResultSet = YES;
    if (_result != result) {
        [_result autorelease];
        _result = [result retain];
    }
}

The reason that we flag if the result has been set is because we want to throw an exception if the subclass implementation of the main method failes to set the result before exiting, we add this behavior by overriding the start method in CWFutureOperation.

The start method will also call the target-action pair upon completion if the operation has not been cancelled. The target selector is always called on the main thread, this is so that we safely can update any UI using the calculated result without adding even more threading code.

-(void)start;
{
    [super start];
    if (![self isCancelled]) {
        if (!_isResultSet) {
            [NSException raise:NSInternalInconsistencyException
                        format:@"%@ did not set result.", self];
        }
        [_completionTarget performSelectorOnMainThread:_completionSelector
                                            withObject:self
                                         waitUntilDone:NO];
    }
}

Conclusion

The total amount of code is not muFuturesch, but this generic class adds a pattern to follow making design decisions for new application easy and consistent.

Solving the age old search-as-you-type problem can be as simple as this (Many assumptions, but you get the idea):

-(NSArray*)performSearchWithString:(NSString*)str;
{
    NSMutableArray* searchResults = nil;
    // Do actual search over the interwebz.
    return searchResults;
}

-(void)searchOperationDidComplete:(CWFutureOperation*)op;
{
    self.currentSearchOperation = nil;
    self.currentSearchResult = [op result];
    [self.searchDisplayController.searchResultsTableView reloadData];
}

-(BOOL)searchDisplayController:(UISearchDisplayController*)controller
  shouldReloadTableForSearchString:(NSString*)searchString;
{
	CWFutureOperation* op = [CWFutureOperation operationWithTarget:self
                                                          selector:@selector(performSearchWithString:) object:searchString];
    [op setCompletionTarget:self
                   selector:@selector(searchOperationDidComplete:)];
    [[NSOperationQueue defaultQueue]
    		replaceOperation:self.currentSearchOperation
               withOperation:op];
    self.currentSearchOperation = op;
    return NO;
}

The full source code including unit tests, and some additional categories for making operation queue life easier, can be downloaded here.

[someTextField performSelectorOnMainThread:@selector(setText:)
                              	withObject:@"A new text"
                             waitUntilDone:YES];

But not everything is an object

Since Objective-C is a superset of C, there are still all the types from C available. Such as all the primitives, including enums, and more complex struct types. Cocoa Touch is pragmatic and will use the most proper type for the use-case, not forcing everything into a square OOP hole.

This makes it quite hard to call for example -[UIView setHidden:], that takes a single BOOL argument. Same for -[UIView setFrame:], that takes a single CGRect struct argument, that in turn consists of one CGPoint and one CGSize struct.

Every type imaginable in C can be bundled in an NSValue instance. So we could bundle up the BOOL primitive, or the CGRect struct in a NSValue object. Then pass that object to the main thread, where it is unbundled and passed to the desired method. Quite cumbersome as it requires us to bundle, and unbundle types manually, and implement at least one extra method.

There must be an easier way

It turns out that NSInvocation can also handle any imaginable C type, or else it would not be able to invoke any imaginable Objective-C method. Making a NSInvocation invoke its method on the main thread is easy enough. Just add a category to the NSInvocation class, with a new method like this:

-(void)invokeOnMainThreadWaitUntilDone:(BOOL)wait;
{
  [self performSelectorOnMainThread:@selector(invoke)
                         withObject:nil
                      waitUntilDone:wait];
}

So now all you need to do is to create a NSInvocation object, fill it in with the primitive or struct types, and invoke it on the main thread. But creating and setting up a NSInvocation object is also a bit on the boring side...

There must be an even easier way!

We could use variable argument lists from plain old C. Too bad that they are untyped?
No despair, we know the target object for our invocation, and we know what method to call. So we have what we need to fetch the NSMethodSignature object for the call, that contains all the type information we need to safely process the va_list.

Our target machine is a Mac running 32- or 64-bit Intel CPU, or an iPhone OS device with a 32 bit ARM CPU. Turns out that on both platforms va_list is simply a void* pointer, to the stack frame. Even better va_start() will always flush any argument passed into the register on the stack frame. So we can skip most of the boring argument handling, by treating the arguments like a byte buffer, only advancing and aligning the buffer according to the information in the NSMethodSignature object.

A convenience method for creating a NSInvocation object for a particular target, selector, and list of variable arguments, would turn out like this:

+(NSInvocation*)invocationWithTarget:(id)target
                            selector:(SEL)aSelector
                     retainArguments:(BOOL)retainArguments, ...;
{
  va_list ap;
  va_start(ap, retainArguments);
  char* args = (char*)ap;
  NSMethodSignature* signature = [target methodSignatureForSelector:aSelector];
  NSInvocation* invocation = [NSInvocation invocationWithMethodSignature:signature];
  if (retainArguments) {
    [invocation retainArguments];
  }
  [invocation setTarget:target];
  [invocation setSelector:aSelector];
  for (int index = 2; index < [signature numberOfArguments]; index++) {
    const char *type = [signature getArgumentTypeAtIndex:index];
    NSUInteger size, align;
    NSGetSizeAndAlignment(type, &size, &align);
    NSUInteger mod = (NSUInteger)args % align;
    if (mod != 0) {
      args += (align - mod);
    }
    [invocation setArgument:args atIndex:index];
    args += size;
  }
  va_end(ap);
  return invocation;
}

Conclusion

And now we can easily call any method on the main UI thread.

An example where a CGRect struct is used to update the UI components frame;

// Set new frame of a label.
[[NSInvocation invocationWithTarget:someLabel
                           selector:@selector(setFrame:)
                    retainArguments:NO, CGRectMake(40, 40, 200, 100)]
 invokeOnMainThreadWaitUntilDone:NO];

A slightly more complex example, where we send a primitive int, and also waits for and fetches the result from the main thread:

// Query a UITableView for the number of rows in section 2.
NSInvocation* i = [NSInvocation invocationWithTarget:tableView
                                            selector:@selector(numberOfRowsInSection:)
                                     retainArguments:NO, (NSUInteger)2];
// Block this thread until method has been invoked and result is available.
[i invokeOnMainThreadWaitUntilDone:YES];
NSInteger numberOfRows;
[i getReturnValue:&numberOfRows];

Download full source code here: NSInvocation+CWVariableArguments.zip

Update: Example 2 was not 64-bit compatible as David Remahl pointed out to me. Added type cast to fix the error.

Update 2: A new version with some more features and small bug-fixes to BOOL, float and uint16_t types, plus proper unit tests can be downloaded here: CWFoundationAsyncAdditions.zip

Dependency injection and early validation is crucial for an enterprise application, and Spring is a boon in this regard. But do not fool yourself, Spring is good, but it is not a universal cure. Especially not in mobile space where startup times, low memory consumption, and avoiding interfaces are virtues.

The bottleneck in an enterprise application is most probably the database, spending a few extra milliseconds here and there seldom matters. On much less performant mobile device those clock cycles are not only time the user has to spend waiting, it will drain the battery. A simple thing as using an interface instead of an abstract superclass will perform at least twice as slow. Even passing an extra argument in the constructors a few nestings deep will have an impact.

Lazy Singeltons by Choice

Class loading in Java is lazy, the Java VM will not load classes until they are referenced. Odds are that the user will not trigger a full coverage of all classes in your app for a short time running mobile app. If the user just checks for incoming messages and quits, then every class involved in composing messages do not need to be loaded. Early dependency injection breaks this, as all classes will be referenced at startup. Most components will be initialized in vain, as they are never actually used.

So what we should do in mobile application is to work more like the Java VM, and less like Spring. If possible do not create a component until it is requested. The best way to do this is using a singleton pattern. Not a normal enforced singleton pattern, but rather a singleton by choice. Let the constructor be public, trust your users, and name the getter getSharedFoo(), not getInstance(). Let me show you using a example of an URL cache component:

public class URLCache {
  private static URLCache sharedCache;

  public static URLCache getSharedURLCache() {
    synchronized (URLCache.class) {
      if (sharedCache == null) {
        sharedCache = new URLCache();
      }
    }
    return sharedCache;
  }

  public URLCache() {
    // More code...
  }
  // Allot more code here...

}

Using this shared URL cache component from our imaginary HTTP provider would then be super easy, but not mandatory:

public class HTTPProvider {

  public InputStream inputStreamForURL(String url) {
    URLCache cache = URLCache.getSharedURLCache();
    // Use the cache...
  }

}

The big win here is that if the code path of this run of the application never tries to open an input stream then the URL cache never has to be created. Saving several hundred milliseconds of reading cache indexes, validation, etc.

But What About Testing?

Are not singletons bad for unit tests and mocking components? They used to be. These days we have PowerMock, you really should use it. Turns out that not even PowerMock is really required, if we just change our singleton pattern very slightly, and allows the outside to set the shared component as well:

public class URLCache {
  private static URLCache sharedCache;

  public static void setSharedURLCache(URLCache cache) {
    synchronized (URLCache.class) {
      sharedCache = cache;
    }
  }

  public static URLCache getSharedURLCache() {
    synchronized (URLCache.class) {
      if (sharedCache == null) {
        sharedCache = new URLCache();
      }
    }
    return sharedCache;
  }

  // Allot more code here...

}

This small addition allows us for setup up our own mock cache in the setup of our unit tests. With something as simple as this:

public class SomeTest extends TestCase {

  public void setUp() {
    URLCache.setSharedURLCache(new NoOpURLCache());
  }

  public void testRemoteResource() {
    assertNotNull(HTTPProvider.getSharedHTTPProvider().inputStreamForURL(TEST_URL));
  }
}

It also allows us for explicitly override a singleton if our application has special needs, perhaps a more aggressive cache on a low bandwidth mobile data connection, or special implementation on a buggy Java ME platform. But most importantly for the normal case it will not waste time creating the component until it is actually needed, vastly improving the user experience for your mobile users.

Take Aways

Do not fear singletons, it is a great way of lazy creations that will greatly improve startup times and memory consumption on mobile applications.

Avoid using interfaces, they are at least twice as slow as classes, and can not have static methods for acquiring the lazy created components.

Do not enforce the singleton pattern, always use singleton by choice. To allow for testing and easy implementation of special cases.

Google Translate to the rescue

Turns out that Google Translate has a nice AJAX API, feed it a URL request and get a JSON response. Admittedly the translations are not always perfect, even quite humorous at times, but good enough if you provide the user a warning.

So let us create a sibling to NSLocalizedString() called CWTranslatedString(). It should take two arguments; the string to translate, and the source language ISO code. We should also be able to get the users currently selected language, that will be used as the destination language when translating. So this is our header:

NSString* CWCurrentLanguageIdentifier();
NSString* CWTranslatedString(NSString* string, NSString* sourceLanguageIdentifier);

Currently your iPhone application must be terminated in order for the user to change the language. And even when Apple adds multitasking for third-party apps we can assume the user do not go about and switch languages too often, so we let CWCurrentLanguageIdentifier() cache the language code:

NSString* CWCurrentLanguageIdentifier() {
    static NSString* currentLanguage = nil;
    if (currentLanguage == nil) {
        NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
        NSArray* languages = [defaults objectForKey:@"AppleLanguages"];
        currentLanguage = [[languages objectAtIndex:0] retain];
    }
    return currentLanguage;
}

Now for the CWTranslatedString() function. The JSON response from Google Translate is well formatted with no line breaks, so let's not bother with a proper JSON-parser. We can use a simple NSScanner, and just return the source string for any unexpected result. We also short circuit and return the source string if the source and dest language as equal.

NSString* CWTranslatedString(NSString* string, NSString* sourceLanguageIdentifier) {
    static NSString* queryURL = @"http://ajax.googleapis.com/ajax/services/language/translate?v=1.0&q=%@&langpair=%@%%7C%@";
    if (sourceLanguageIdentifier == nil) {
        sourceLanguageIdentifier = @"en";
    }
    if ([sourceLanguageIdentifier isEqual:CWCurrentLanguageIdentifier()] || string == nil) {
        return string;
    }
    NSString* escapedString = [string stringByAddingPercentEscapesUsingEncoding:NSUTF8StringEncoding];
    NSString* query = [NSString stringWithFormat:queryURL,
                       escapedString, sourceLanguageIdentifier, CWCurrentLanguageIdentifier()];
    NSString* response = [NSString stringWithContentsOfURL:[NSURL URLWithString:query]
                                                  encoding:NSUTF8StringEncoding error:NULL];
    if (response == nil) {
        return string;
    }
    NSScanner* scanner = [NSScanner scannerWithString:response];
    if (![scanner scanUpToString:@"\"translatedText\":\"" intoString:NULL]) {
        return string;
    }
    if (![scanner scanString:@"\"translatedText\":\"" intoString:NULL]) {
        return string;
    }
    NSString* result = nil;
    if (![scanner scanUpToString:@"\"}" intoString:&result]) {
        return string;
    }
    return result;
}

And that is it. Not perfect, but nice to have.

Clicking on the first link you expect your browser to start a new tab and navigate to the url that was specified in the href. If you click on the second link you would expect that the browser opens up your favourite email client. The third link would probably just give you an error message since the browser has no idea how to react on a link like foo://my.test.com

On Android we can control how the device should react when the user clicks on a link in the web browser, or more specific control which Activity should be started. Every time the user clicks on a link the browser sends an intent to the platform with the following content.

action = android.intent.action.VIEW
category = android.intent.category.BROWSABLE
data = the text from the href tag

If we navigate to a web page with the following page source on our Andoid device we could expect a few interesting things to happen when we click on the links.

The first link will generate an intent with the following information

action = android.intent.action.VIEW
category = android.intent.category.BROWSABLE
data = "tel:123456"

This will start the Dialer application and preset the phone number to 123456.

Clicking on the second link will not surprisingly open up the email client in your device with a preset receiver address. What about clicking on the third link? Well, by default it would just return a "page not available" error message in the browser. The intent sent from the browser will look like this

action = android.intent.action.VIEW
category = android.intent.category.BROWSABLE
data = "foo://my.test.com"

This means that if we install an Activity with the following IntentFilter

this Activity will start when the user clicks on the third link. Pretty cool, isn't it?

Creating a perfect Default.png is impossible, especially if you have different setup of navigation and tab bars in different parts of your app. And even harder to adjust for the different sizes of the status bar. With the advent of tethering the size of the status bar is even more sure to be random at startup. This adds to a small jerk, or ugly jump of the user interface at start up.

Create a smooth startup

The easiest way to counter this small jerk is to let your user interface fade in. It is pleasing to the eye, and easy to do. So easy that this blog post pretty much ends after a small code block you can cut&paste into any of your projects.

If you create your UI using Interface Builder, or create it in code, you still have an implementation of applicationDidFinishLaunching: that ends like this:

-(void)applicationDidFinishLaunching:(UIApplication*)application;
{
// ...more code...
  [window makeKeyAndVisible];
}

This is where we will add our own code that will slide in a new view, above the root view, mimicking the Default.png look. This view is then quickly faded out and removed, creating the appearance of fading in our real user interface.

-(void)applicationDidFinishLaunching:(UIApplication*)application;
{
// ...more code...
  UIImage* backImage = [UIImage imageNamed:@"Default.png"];
  UIView* backView = [[UIImageView alloc] initWithImage:backImage];
  backView.frame = window.bounds;
  [window addSubview:backView];
  [UIView beginAnimations:@"CWFadeIn" context:(void*)backView];
  [UIView setAnimationDelegate:self];
  [UIView setAnimationDidStopSelector:
      @selector(animationDidStop:finished:context:)];
  [UIView setAnimationDuration:0.5f];
  backView.alpha = 0;
  [UIView commitAnimations];
  [window makeKeyAndVisible];
}
 
-(void)animationDidStop:(NSString*)animationID finished:(NSNumber*)finished
    context:(void*)context
{
  UIView* backView = (UIView*)context;
  [backView removeFromSuperview];
  [backView release];
}

And that is it, instant better first impression.

Any sane developer avoids premature optimization, so the task we later want to execute in a separate thread is almost always available in our current context. I am sure all Java-developers has seen something like this:

 new Thread() {
    public void run() {
        OuterClass.this.someMethod(arg);
    }
}.start();

And often an anonymous Runnable is involved as well. Executing a task in a separate thread with Cocoa and Cocoa Touch is ridiculously easy given the dynamic nature of Objective-C. This is done with Cocoa with this one-liner:

[self performSelectorInBackground:@selector(someMethod:) withObject:arg];

The performSelectorInBackground:withObject: is a companion method for performSelector:withObject:, and will create a new NSThread instance, and execute the specified method there. There are more companions such as performSelectorOnMainThread:withObject: that is used to execute a method on the main UI thread.

This easy access to executing in new threads often can result in code that spawns too many threads. In Cocoa on Mac OS X this is seldom a problem, not for Cocoa Touch applications under development when running in the iPhone simulator either. But on the more resource constrained iPhone and iPod Touch devices this will be a problem. Spawning a dozen background threads to download images will bring the iPhone OS to a staggering mess.

Update: I have removed CWSelectorOperation from this post, since using NSInvocationOperation is preferred.

Operation Queues

The solution is to use a NSOperationQueue, that as the name implies handles a queue of operations. The max number of concurrent operations can be set, as well as dependencies and priority. The downside is that NSOperationQueue can only handle instances of NSOperation.

NSOperation is an abstract class, where you as a developer override the main method to execute your task. In short NSOperation is programatically the equivalent of the Java Runnable interface. It is even worse as Objective-C do not support anonymous classes, so we will be required to actually implement our queued tasks as separate classes.

Not as neat as one would like, and definitely not even very Cocoa-like.

What is Missing

As a Cocoa developer I expect that executing a task on background queue, would be just as easy as executing a task on a background thread. The expected needed code is something like this:

[self performSelectorOnBackgroundQueue:@selector(someMethod:) withObject:arg];

To make this work we need:

1. A category on NSObject to add performSelectorOnBackgroundQueue:withObject:.
2. Implement a concrete subclass of NSOperation to support execution of a selector on any target.Use NSInvocationOperation to perform selector.
3. A category on NSOperationQueue to add a shared operation queue.

This is in the order of how a client developer would see it (most developers will only care for the NSObject category). For us this is the reverse order when implement this functionality.

A Shared Operation Queue

Cocoa and Cocoa Touch used many shared instances, for example a shared UIAccelerometer instance, and a shared NSURLCache instance. So this pattern of single point dependency injection is common in Cocoa and works very well. So let us follow suit by introducing an interface like this:

@interface NSOperationQueue (CWSharedQueue)
+(NSOperationQueue*)sharedOperationQueue;
+(void)setSharedOperationQueue:(NSOperationQueue*)operationQueue;
@end

The shared operation queue will be created lazily if it do not exist, and the client can easily swap it out at startup if needed. The implementation is very small, and a good example of how we should implement class variables with proper memory handling.

@implementation NSOperationQueue (CWSharedQueue)
 
static NSOperationQueue* cw_sharedOperationQueue = nil;
 
+(NSOperationQueue*)sharedOperationQueue;
{
  if (cw_sharedOperationQueue == nil) {
    cw_sharedOperationQueue = [[NSOperationQueue alloc] init];
    [cw_sharedOperationQueue setMaxConcurrentOperationCount:3];
  }
  return cw_sharedOperationQueue;
}
 
+(void)setSharedOperationQueue:(NSOperationQueue*)operationQueue;
{
  if (operationQueue != cw_sharedOperationQueue) {
    [cw_sharedOperationQueue release];
    cw_sharedOperationQueue = [operationQueue retain];
  }
}
 
@end

Enter CWSelectorOperation

Update: CWSelectorOperation is no longer needed, our implementation instead uses NSInvocationOperation.

Wrapping up NSObject

And at last we reach the category on NSObject, that is what we initially wanted, and what 95% of all use cases will be limited to.

@interface NSObject (CWSharedQueue)
 
-(NSInvocationOperation*)performSelectorInBackgroundQueue:(SEL)aSelector
    withObject:(id)arg;
-(NSInvocationOperation*)performSelectorInBackgroundQueue:(SEL)aSelector
    withObject:(id)arg dependencies:(NSArray*)dependencies
    priority:(NSOperationQueuePriority)priority;
 
@end

Most performSelector* methods do not have a return value, I have chosen to return the resulting NSInvocationOperation so that it can be used to setup dependencies for future queued operations. I have also added a second method performSelectorInBackgroundQueue:withObject:dependencies:priority: so that such dependencies can easily be setup, as well as prioritisation of operations.

The actual implementation is a simple wrapper around the NSInvocationOperation class, and category on NSOperationQueue that we implemented above:

@implementation NSObject (CWSharedQueue)
 
-(NSInvocationOperation*)performSelectorInBackgroundQueue:(SEL)aSelector
    withObject:(id)arg;
{
  NSInvocationOperation* operation = [[NSInvocationOperation alloc]
      initWithTarget:self selector:aSelector object:arg];
  [[NSOperationQueue sharedOperationQueue] addOperation:operation];
  return [operation autorelease];
}
 
-(NSInvocationOperation*)performSelectorInBackgroundQueue:(SEL)aSelector
    withObject:(id)arg dependencies:(NSArray*)dependencies
    priority:(NSOperationQueuePriority)priority;
{
  NSInvocationOperation* operation = [[NSInvocationOperation alloc]
      initWithTarget:self selector:aSelector object:arg];
  [operation setQueuePriority:priority];
  for (NSOperation* dependency in dependencies) {
    [operation addDependency:dependency];
  }
  [[NSOperationQueue sharedOperationQueue] addOperation:operation];
  return [operation autorelease];
}
 
@end

And that is it, if you want to avoid cut and paste of all this code to your own project just download the source code here. And happy concurrent hacking.

Download the older source code here, with a concrete subclass of NSOperation called CWSelectorOperation.

Or are regular expressions really missing? Regular expressions can be used with NSPredicate that is part of Core Data, available since Mac OS X 10.4 and officially announced for iPhone OS 3.0. Cocoa's WebView and the equivalent UIWebView in Cocoa Touch both support JavaScript with regular expressions. So there sure is regular expressions available on the platforms, but how do you make it available for your own code?

An Ugly Solution

You can actually get access to the regular expression engine through JavaScript, unfortunately this requires a roundtrip through WebKit. On an iPhone this means you have to use an off-screen instance of UIWebView, and delegate execution of regular expression to it.

The complexity of an off-screen WebView or UIWebView could be hidden by a utility class. But the extra glue code needed to make something useful out of the single method stringByEvaluatingJavaScripFromString:, would be allot.

What Apple Recommends

For most problems the official stance is correct; do not use regular expressions. Instead use NSScanner, that is perfect for sequentially parse texts. It is very fast and can substitute any regular expressions that only relies on:

• Character sets
• Exact string matches
• Numerical matches
• Uniform input text

These conditions hold true to 95% of everything regular expressions is ever used for. For the other 5%, Apple leaves you to fend for your own.

Other Solutions

PCRE compiles perfectly with Cocoa, since it is written in C, one of the many advantages of Objective-C. PCRE is very capable, and almost a standard, but also very large. For an iPhone application the PCRE implementation could end up as the majority of your executables file-size. If this is something you can live with, then the open source RegexKit framework wraps PCRE in Cocoa and Cocoa Touch friendly Objective-C.

Another regular expressions framework is OgreKit. The advantage of OgreKit is full unicode support, with the same disadvantage of size. And the fact that the documentation is in Japanese.

A Pretty Solution

It turns out that Mac OS X for years, and iPhone OS since inception, has been shipped with a perfectly good regular expressions engine. This engine is based on the ICU specification, so it works perfectly with unicode and is well on par with PCRE for functionality. This framework is simply called ICU Core, and has a C interface. But for a Cocoa programmers the C interface is not nice enough, and thankfully John Engelhart has done this work for us, with RegexKitLite. RegexKitLite is a little brother to RegexKit that wrapps ICU Core instead of PCRE.

RegexKitLite is published under BSD license, and is simply two files you add to your project, fully compatible with all available versions of both Mac OS X and iPhone OS. The tricky part is that ICU Core is not a public API officially supported by Apple, even though it has existed unchanged for years. Good news is that using ICU Core is not a show stopper for publishing on the iPhone App Store, application out there already uses it, both well known and not so well known.

Setting Up RegexKitLite

1. Download the latest version from the sourceforge webpage, or SVN.
2. Add RegexKitLite.h and RegexKitLite.m to your project.
3. Link your project against ICU Core, by adding the linker flag -licucore to Other Linker Flags under your projects build settings.

Optionally you can also add the documentation to Xcode with these easy steps:

1. Open Help -> Documtantion.
2. Press the Gears button in the lower left corder, and select New Subscription....
3. Enter feed://regexkit.sourceforge.net/RegexKitLiteDocSets.atom as URL.

Using RegexKitLite

This post is not a tutorial on regular expressions, but a tutorial on a partical API for executing regular expressions. If you want to learn more about regular expressions themselves I would recomend you look at Regular Expressions.info.

RegexKitLite provides it's functionality as categories on NSString and NSMutableString. This way using regular expressions with Cocoa is just as easy and normal string manipulation. This is best described using examples.

A simple example that normalizes a text with single white spaces, kind of like how a HML renderer would do, so this is handy when scraping web pages:

NSString* source = @"One\t Two \nThree ";
NSString* result = [source stringByReplacingOccurancesOfRegex:@"\\s+"
    withString:@" "];
NSLog(source);
NSLog(result);

Or you can split a text, such as semi-colon delimeted data:

NSString* source = @"Test;12;Y";
NSArray* columns = [source componentsSeparatedByRegex:@";\\s*"];
NSLog([columns description]);

And you can extract more complex data using capture groups:

NSString* source = @"<foo no=\"12\">Name</foo>";
NSString* regex = @"<foo no=\"(.+?)\">(.*?)</foo>";
int no = [[source stringByMatching:regex capture:1] intValue];
NSString* data = [source stringByMatching:regex capture:2];
NSLog(@"no: %d data: %@", no, data);

This may look like it could be slow to perform matches on the same regular expression twice, but it is not. RegexKitLite is very smart, and will cache your previous matches for very high performance.

RegexKitLite is a very capable, and also much active open source project, with version 3.0 as a release candidate in SVN. Use it, and use it well.

Creating a SD card image
In both the 1.1 and 1.5 version of the SDK there is a tool called mksdcard located in the SDK Install Dir/tools folder. Simply run

./mksdcard 128M my128MbCard

to create a 128Mb SD card with the name my128MbCard.

Mounting a SD card image in Linux
To be able to put content on to the card you can mount the card in Linux. It will then simply appear as a folder in the filesystem.
First make a directory in the /media folder:

sudo mkdir /media/mycard

Then mount the card as a loopback device:

sudo mount -o loop my128MbCard /media/mycard

Adding content to the card
With content we usually mean media content like images and videos. Images and videos are located in a folder called /dcim/Camera. You could of course add any content to the card. When you are done copying your files be sure to umount the card otherwise it will not be usable from the emulator.

sudo umount /media/mycard/

Using the card in the emulator
Google added something called Android Virtual Device (AVD) to the SDK 1.5. To create a new AVD using our newly created SDcard image run the following:

./android create avd --name myAVD --target 2 --sdcard my128MbCard

Target 2 means that we want to use the 1.5 API features in the device. Now we simply fire up the emulator and start using our content:

./emulator -avd myAVD

More information about the new SDK can be found here: SDK

NSArray admits to sorts being a slow operation, and adds a method pair for comultive sorts using hints. This way the operation is done in O(P*LOG(P)+N) time, instead of O(N*LOG(N)). Where N is number of elements, and P is number of additions and deletions since the last sort. Unfortunately that do not work on NSMutableArray. So even if memory consumption will not hit the roof, release retain cycles will take it's toll.

So why not add methods to find the insertion points, and insert new objects into already sorted NSArray and NSMutableArray object? Best case for inserting single elements should be O(LOG(N)^2), so lets hit that target. And on the way there, we will learn how to;

• Add functionality to standard classes using categories.
• Implement high performant Obj-C code for tight loops.

New Categories on NSArray and NSMutableArray

This will become a bit complex on the inside, but the public front should be as simple as this:

#import <Foundation/Foundation.h>
 
@interface NSArray (CWSortedInsert)
 
-(NSUInteger)indexForInsertingObject:(id)anObject
    sortedUsingfunction:(NSInteger (*)(id, id, void *))compare
    context:(void*)context;
-(NSUInteger)indexForInsertingObject:(id)anObject
    sortedUsingSelector:(SEL)aSelector;
-(NSUInteger)indexForInsertingObject:(id)anObject
    sortedUsingDescriptors:(NSArray*)descriptors;
 
@end
 
@interface NSMutableArray (CWSortedInsert)
 
-(void)insertObject:(id)anObject
    sortedUsingfunction:(NSInteger (*)(id, id, void *))compare
    context:(void*)context;
-(void)insertObject:(id)anObject sortedUsingSelector:(SEL)aSelector;
-(void)insertObject:(id)anObject sortedUsingDescriptors:(NSArray*)descriptors;
 
@end

Base Implementation

We want to follow suit with NSArray and NSMutableArray, so we too shall support inserts based on functions, selectors, and an array of sort descriptors. In practice we only need to implement indexForInsertingObject:sortedUsingfunction:context:, the other methods can use this one, each with a private compare method of their own. So we begin by implementing this method.

#import "NSArray+CWSortedInsert.h"
#import <objc/runtime.h>
 
@implementation NSArray (CWSortedInsert)
 
-(NSUInteger)indexForInsertingObject:(id)anObject
    sortedUsingfunction:(NSInteger (*)(id, id, void *))compare
    context:(void*)context;
{
  NSUInteger index = 0;
  NSUInteger topIndex = [self count];
  IMP objectAtIndexImp = [self methodForSelector:@selector(objectAtIndex:)];
  while (index < topIndex) {
    NSUInteger midIndex = (index + topIndex) / 2;
    id testObject = objectAtIndexImp(self, @selector(objectAtIndex:), midIndex);
    if (compare(anObject, testObject, context) < 0) {
      index = midIndex + 1;
    } else {
      topIndex = midIndex;
    }
  }
  return index;
}
 
// More code here...
 
@end

The Objective-C runtime header is included so we can go around the usual method dispatch, and instead use the method implementations as function pointers. In most cases this is a neglectable optimization, for this case we will be the bottle neck since we are intended to be the low level API.

The algorithm is a simple binary search, and we have a worst case O(LOG(N)^2) time for index search. Using this for implementing the sibling method in NSMutableArray is as simple as this:

@implementation NSMutableArray (CWSortedInsert)
 
-(void)insertObject:(id)anObject
    sortedUsingfunction:(NSInteger (*)(id, id, void *))compare
    context:(void*)context;
{
  NSUInteger index = [self indexForInsertingObject:anObject
      sortedUsingfunction:compare context:context];
  [self insertObject:anObject atIndex:index];
}
 
// More code here...
 
@end

Sort Using Selector

With functions in place, writing a utility compare function that uses selectors, and can be used with our indexForInsertingObject:sortedUsingfunction:context: method is a breeze.

static NSComparisonResult cw_SelectorCompare(id a, id b, void* aSelector) {
  return (NSComparisonResult)objc_msgSend(a, (SEL)aSelector, b);
}
 
-(NSUInteger)indexForInsertingObject:(id)anObject
    sortedUsingSelector:(SEL)aSelector;
{
  return [self indexForInsertingObject:anObject
      sortedUsingfunction:&cw_SelectorCompare context:aSelector];
}

Notice that objc_msgSend(id, SEL, ...) is used instead of the performSelector:withObject: method. This is a small performance improvement, as what performSelector:withObject: do behind the scene is just a call to objc_msgSend() anyway. We have removed one method invokation per compare.

Sort Using Sort Descriptors

Or rather sort with an array or NSSortDescriptor objects. This will be the least performant, but also the most flexible sort. An array of sort descriptors is used because we want to be able to sort using several criteria, one sort descriptor per criteria. For example when sorting on last name, then first name, or even more complex sorts.

A NSSortDescriptor is initialized with a key, sort order (ascending or descending) and optionally a selector to do the comparison with, by default compare:. There are quite a few method invokations involved, and it will be good for performance to avoid as many as we can.

Just as performSelector:withObject: uses objc_msgSend() behind the scene, so do objc_msgSend use a function pointer internally. After doing a hash-table lookup with the selector as key that is. This look-up is cached and very fast, but avoiding it all together is always faster. So let us fetch those when the category is first loaded, and do our calls straight through the functions pointers avoiding at least two or more function calls for each compare operation.

static IMP cw_compareObjectToObjectImp = NULL;
static IMP cw_ascendingImp = NULL;
 
+(void)initialize;
{
  cw_compareObjectToObjectImp = [NSSortDescriptor
      instanceMethodForSelector:@selector(compareObject:toObject:)];
  cw_ascendingImp = [NSSortDescriptor
      instanceMethodForSelector:@selector(ascending)];
}

The class method inilialize is kind of magic, it is called once for each class and category, when the class or category is loaded into the run-time. It is the Obj-C equivalent of static initializers.

With the function pointers to the hot-spot method implementations in hand, here is the fast implementation:

static NSComparisonResult cw_DescriptorCompare(id a, id b, void* descriptors) {
  NSComparisonResult result = NSOrderedSame;
  for (NSSortDescriptor* sortDescriptor in (NSArray*)descriptors) {
    result = (NSComparisonResult)cw_compareObjectToObjectImp(sortDescriptor,
        @selector(compareObject:toObject:), a, b);
    if (result != NSOrderedSame) {
      if (!cw_ascendingImp(sortDescriptor, @selector(ascending))) {
      	result = 0 - result;
      }
      break;
    }
  }
  return result;
}
 
-(NSUInteger)indexForInsertingObject:(id)anObject
    sortedUsingDescriptors:(NSArray*)descriptors;
{
  return [self indexForInsertingObject:anObject
      sortedUsingfunction:&cw_DescriptorCompare context:descriptors];
}

Conclusions

The fact that Objective-C is a strict superset of C have some good benefits. The obvious one is that your Obj-C code is both source-code and binary compatible with the vast collection of code that has been written in C over the past 30+ years.

The second benefit is that when performance is needed, Obj-C gives us as developers full access to the internals of the dynamic run-time.

But best of all, most developers never need to care. They can, blissfully unaware, reap the benefits of the performance tuning under the hood. Tuning by both Apple and considerate third party library developers willing to go the extra mile (or a few metres at least).

The code is released under BSD license, and works on both Mac OS X and iPhone OS. You can download it here.

By using the setContentView(int layoutResId) method of the Activity class your layout will be displayed on the screen. Behind the scenes the Android platform is creating all the view objects contained in your layout xml file provided to the setContentView(int layoutResId) method. This process of creating view objects out of layout resources is referred to as layout inflation.

So far so good. This means that before the setContentView(int layoutResId) method is called the findViewById(int resId) method will return null for any view references in the layout, causing some potential NullpointerExceptions.

@Override
public void onCreate(Bundle savedInstanceState) {
   super.onCreate(savedInstanceState);
 
   EditText addressField = (EditText) findViewById(R.id.address); //To early!! Will return null
   setContentView(R.layout.main);
   Button button = (Button) findViewById(R.id.launchMap);
 
   addressField.setText("Some Text");	//NullPointerException
   button.setText("Some other text");	//No problem
}

To avoid these errors it's a good habit to place the setContentView(int layoutResId) method call at the very top of the onCreate() method.

In some cases you will have to do the layout inflation by yourself, i.e. when you want to set a custom view to a Dialog or a Toast. To inflate a view you use the LayoutInflater class. There's a number of different ways to get a handle to a LayoutInflater:

LayoutInflater inflater = (LayoutInflater)context.getSystemService(
      Context.LAYOUT_INFLATER_SERVICE);
 
LayoutInflater inflater = LayoutInflater.from(context);

To actually create the view object you use the inflate() method of the LayoutInflater. In the most straightforward form this method has the signature:

public View  inflate(int resource, ViewGroup root)

Note that the resource is referring to a layout xml file resource, NOT the id of the view object that you want to inflate. First inflate the layout resource and then get a handle to the view object by using the findViewById(int resId) method.

The second attribute allows you to specify a ViewGroup object to be the root view of the inflated object(s) specified by your layout xml file. This means that the inflated view object(s) are attached as child views on the specified root ViewGroup object. Setting this value to null will simply return the inflated view object(s) without attaching them to a root view.

EditText fooField = (EditText) findViewById(R.id.foo); //To early!! Will return null
LinearLayout myRoot = new LinearLayout();
View itemView = inflater.inflate(R.layout.layout_details, myRoot);  //from layout_details.xml
EditText barField = (EditText) findViewById(R.id.bar); //Now we have an object

In this example the inflate method returns the mRoot object with the view objects contained in the layout_details.xml file attached as child views. So itemView and myRoot is actually referring to the same physical object.

Here I will use a small example that is easy and natural for Ruby, but equally hard for Java and Obj-C. That way both languages stand on equal grounds for comparison.

This article explains the Objective-C parts in detail, and Java in brief. It is assumed that you as a reader understands Java well. Many concept in Java and Obj-C are identical, but with different names. I will be using the Java names in Java context, and the Obj-C names in Obj-C context. Therefore; memorize this short glossary:

Java      -> Obj-C
interface -> protocol
this      -> self
null      -> nil

Cocoa relies heavily on features in the Obj-C langauges, so even if Cocoa apps can be written, and is so supported by Apple, in Ruby or Python; Obj-C is the only language that can tap into the full power of Cocoa.

Cocoa on Mac OS X is an umbrella framework for Foundation and AppKit. Cocoa Touch on iPhone OS is an umbrella framework for Foundation and UIKit. This post only uses features from the shared Foundation framework, and this is applicable for both Mac OS X and iPhone OS.

The Ruby Problem

Ruby makes it extremely easy to work with arrays. For the sake of this post I want to convert an array of numbers into an array of strings. Performing the same operation on an arbitrary list of objects, and then resturn a list with the results.

list = [12, 42, 366]
results = list.collect { |item| item.to_s }
puts results

First line sets up an array of numbers, and the second line creates a new array by executing a block against each element, and then we print it out. The block can be seen as a closure, Java nor Obj-C have closures, at least not yet. Objective-C 2.1 will be public this summer and introduce blocks, that can be seen as closures.

With no closures at hand today, both Java and Obj-C will have to solve the problem by executing a method on each element. In this example toString() in Java and the Cocoa equivalent description.

Java Implementation

For the Java implementation we need to introduce a utility class. This utility class I call ListCollector, and it uses generics to allow for different kinds of inputs and results. This utility class could be implemented like this:

public class ListCollector {
 
    public interface Collector<R, E> {
        public R collect(E element);
    }
 
    public static <R, E> List<R> collect(List<E> list, Collector<R, E> collector) {
        List<R> results = new ArrayList<R>(list.size());
        for (E item : list) {
            R result = collector.collect(item);
            results.add(result);
        }
        return results;
    }
 
}

Our utility function collect takes two arguments; a List with elements, and a Collector implementation to invoke on each element. This do not use a closure as in the Ruby example.

A simple example of how to use this utility in the same veine as in the previous Ruby example:

public class Example {
    public static void main(String[] args) {
        List<Number> list = new ArrayList<Number>();
        list.add(12);
        list.add(42);
        list.add(366);
 
        List<String> results = ListCollector.collect(list,
                new ListCollector.Collector<String, Number>() {
                    public String collect(Number element) {
                        return element.toString();
                    }
                });
 
        System.out.println(results);
    }
}

Cocoa Interaface

In Cocoa you never have utility classes, instead you use categories to add new functions to already existing classes. A category can be seen as a mix-ins, it allows us to add and replace class and instance methods, as well as protocol conformance on already existing classes.

That is the good stuff, the bad stuff is that Obj-C do not know of final. So if an implementation is brittle, the only safety against bad programmers is the documentation you write. In fact Obj-C do not know of visibility, all methods are public. You can only hide a method by not displaying it in the public interface of your classes (your users may still guess at the names and use it anyway).

That leads us to interfaces, Obj-C just as C and C++ uses interface files; .h files. So lets define our category:

#import <Foundation/Foundation.h>
 
@interface NSArray (CWCollect)
 
-(NSArray*)resultsFromMakingObjectsPerformSelector:(SEL)aSelector
        withObject:(id)anObject;
 
@end

First thing we note here is that the method name is quite long; resultsFromMakingObjectsPerformSelector:withObject:, and that arguments are interleaved. At first glance it might look like named arguments, this is an illusion, they are merely interleaved with the : character. Looks strange, but the result is surprisingly readable and self describing code.

Note that is do not use a closure as in Ruby, nor an inner class as in Java, but a reference to a method identifier in the form of the SEL argument.

Cocoa Implementation

Just as C and C++ has interface files, so do Obj-C have implementation files; .m files, or .mm for Objective-C++ where you can mix C++ with Objective-C.

The implementation is quite familiar:

#import "NSArray+CWCollect.h"
 
@implementation NSArray (CWCollect)
 
-(NSArray*)resultsFromMakingObjectsPerformSelector:(SEL)aSelector
        withObject:(id)anObject;
{
    NSMutableArray* results = [NSMutableArray arrayWithCapacity:[self count]];
    for (id<NSObject> item in self) {
        id result = [item performSelector:aSelector withObject:anObject];
        [results addObject:(result != nil) ? result : [NSNull null]];
    }
    return [[results copy] autorelease];
}
 
@end

First we create a NSMutableArray, in Cocoa there are two classes for arrays; NSArray that is immutable, and the subclass NSMutableArray that is mutable. Then we use the for each statement to iterate over our input array. Then comes the first real difference from Java, and a clear display of the dynamic nature. Obj-C, nor Cocoa have support for generics. The use of the generic id object type avoids the need for most typecast, but you should be aware that they implicitly are there.

Methods are first class citizens in Obj-C, not tucked away in a utility package. A method in Obj-C consists of two parts; the selector and the implementation. The selector has the type SEL, and the implementation is IMP. Both can be passed around just as any other primitive type or object instance.

The selector is the identification of the method, think of it as the name. The selector is shared for all classes implementing a method with the same signature. If one class implements someMethod: and another class, in a completely other even dynamically loaded framework, also implements someMethod: both are guaranteed to be equal. The root object NSObject in Cocoa implements methods for dynamically invocing methods baseds on selectors, one of them is the one used in the code above performSelector:withObject:.

The implementation of a method is a function pointer to the actual executable code that implements the method. It can be shared between classes, as is often the case for subclasses. But can also be freely passes around, and exchanged for some quite powerful and useful tricks.

Cocoa Use-case Example

Obj-C is a strict superset of C, so just as you have a main function in C, so do Obj-C. For most Cocoa application you never need to worry about this, the template from Xcode will generate the main function and all you see is OOP goodnes. For this small example I will do the test code in a main function of my own. If you cut and paste code from this example, be sure to create a project from the "Command Line Utility"->"Foundation Tool" template in Xcode.

#import <Foundation/Foundation.h>
#import "NSArray+CWCollect.h"
 
int main (int argc, const char * argv[]) {
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
 
    NSArray* list = [NSArray arrayWithObjects:[NSNumber numberWithInt:12],
            [NSNumber numberWithInt:42], [NSNumber numberWithInt:336], nil];
 
    NSArray* result = [list
            resultsFromMakingObjectsPerformSelector:@selector(description)
            withObject:nil];
 
    NSLog([result description]);
 
    [pool drain];
    return 0;
}

The NSAutoreleasePool is part of Cocoa, and is used to seemingly garbage collected framework. Cocoa for Mac OS X can be garbage collected, Cocoa Touch for iPhone OS is not garbage collected.

The second statement created an array instance with three NSNumber objects. NSNumber is equivalent to java.lang.Number and all of it's subclasses, Cocoa do not have a separate subclass of NSNumber for each primitive type. NSNumber is a subclass of NSValue, that can hold any C type value including structs and unions.

The third statement is where we call the method we defined and implemented above. Note how we call this on a stock Cocoa class, not on a utility class. We use the @selector() compiler directive to retrieve a selector of SEL type from a human readable name, and pass nil the Objective-C equivalent of null as argument.

Lastly we send the result converted to a string to NSLog() function. NSLog() is a C macro with printf syntax that is used to send text to standard out. NSLog() can be removed from release builds.

Last Words

It is important to understand the concept of selectors, and how passing around SEL arguments works. In Java libraries callbacks are often handles using listener interfaces, where the listener implements an interface and a specific method is called. In Cocoa listeners are implemented using the target-action paradigm, where the intended listener is passed along with the SEL specifying which method to send the callback to.

As an example when setting up the event listener for user tapping a control in Cocoa Touch on iPhone OS:

[myButton addTarget:self action:@selector(buttonTapped:)
        forControlEvents:UIControlEventTouchUpInside];

What this means is that the need for anonymous inner classes is removed, and the same class can in a natural way receive the same event from different senders.

For more complex, or grouped event handling protocols are used. The classes conforming to the listeners protocols are not referred to as listener, but as delegates, yet again different name but same concept. But even now the dynamic language come into play, as a class is not required to implement all methods from a protocol in order to conform to it (Think of it as if some methods in a Java interface could be optional, and then are treaded as no-ops).

A protocol in Obj-C can have optional methods. Implementor of the NSTableViewDataSource protocol may for example choose to implement, or not to implement the method tableView:setObjectValue:forTableColumn:row:. If not implemented the table is read-only, by implementing this single method the table is editable and functionality such as pasting into the cells is provided for free.

It is very important for developers new to Cocoa and Obj-C to grasp the concepts of target-action, and delegates. This is the core principles that drive the application frameworks for Mac OS X and iPhone OS.

The Problem

The most intuitive way to create and use a UIToolbar is to add it manually for each of your view controllers. If your application is very simple this could be the right thing to do, but if our application uses a UINavigationController then it is the wrong way to do it.

If you look at the Mail application you will notice how the toolbar stays in place, and the items on the toolbar cross fades when you navigate the application hierarchy. You might also have noticed that the toolbar do not cross fade, but rather is pushed, if you add a toolbar to each of the view trees of your own view controllers. This is because your toolbar is then part of the wrong three hierarchy, as shown in this image.

Screen estate as owned by different view controllers.

You will find a few solutions if you Goole on the topic, all of them that I have found are dead wrong. They tend to use self.view.superview on the view controller instance to slide the toolbar up one level in the hierarchy. It works, most of the time, but is an ugly hack that is not future proof.

A Better Solution

The reason the toolbar is pushed off screen is that the toolbar is owned by the navigation controller,as we saw in the image above, and a navigation controller pushes it's content. The view hierarchy we would like to have is instead something like this.

Screen estate as owned by different view controllers.

In this setup the navigation controller can push the content, as it is intended to do, and the custom toolbar controller can manage a static UIToolbar with cross fades. Only problem is; this custom toolbar controller do not exist, and we must implement it on our own. Luckily not many lines of code is needed.

Custom Toolbar Conroller Requirement

The custom toolbar controller should be a subclass of UIViewController, that way it's fits nicely into the Cocoa Touch framework, and can nicely be fitted into any well written application.

The custom toolbar controller should manage a view consisting of a UIToolbar instance, and a view that is fetched from another view controller. This is modelled after how a UINavigationController manages a view that consists of a UINavigationBar and the view fetched from other view controllers. This way any well written view controller can be used with our custom toolbar controller.

Lastly our custom toolbar controller should implement the UINavigationControllerDelegate protocol, so that we can listen to events as view controllers are pushed and poped from the navigation stack, and update the toolbar with contextual toolbar items. Just as the navigation controller updates it's title by fetching the title property of the managed view controllers, so will our custom toolbar controller update the toolbar items by fetching the toolbarItems property if available.

Toolbar Controller Interface

The interface will be sparse, all we need is an initializer for creating a toolbar controller with another view controller providing the main content, and for sports two properties to access the content view controller, and the toolbar itself.

#import <UIKit/UIKit.h>
 
@interface CWToolbarController : UIViewController <UINavigationControllerDelegate> {
@private
    UIViewController* _contentViewController;
    UIToolbar* _toolbar;
}
 
@property(nonatomic, retain, readonly) UIViewController* contentViewController;
@property(nonatomic, retain, readonly) UIToolbar* toolbar;
 
-(id)initWithContentViewController:(UIViewController*)contentViewController;
 
@end

Toolbar Controller Implementation

The grunt work for implementing the toolbar controller do not need any further explanation.

#import "CWToolbarController.h"
 
@implementation CWToolbarController
 
@synthesize contentViewController = _contentViewController;
@synthesize toolbar = _toolbar;
 
- (id)initWithContentViewController:(UIViewController*)contentViewController;
{
    self = [super init];
    if (self) {
        _contentViewController = [contentViewController retain];
        if ([_contentViewController isKindOfClass:[UINavigationController class]]) {
            ((UINavigationController*)_contentViewController).delegate = self;
        }
    }
	return self;
}
 
// More code here...
 
- (void)dealloc;
{
    [_contentViewController release];
    [super dealloc];
}
 
@end

The first interesting code is to setup the view that is managed by our toolbar controller. This view have two subviews, a UIToolbar, and a view that we fetch from the content view controller we where given. We do this setup in the loadView method.

- (void)loadView;
{
    UIView* contentView = _contentViewController.view;
    CGRect frame = contentView.frame;
    UIView* view = [[UIView alloc] initWithFrame:frame];
 
    frame = CGRectMake(0, 0, frame.size.width, frame.size.height - 44.0f);
    contentView.frame = frame;
    [view addSubview:contentView];
 
    frame = CGRectMake(0.0f, frame.size.height, frame.size.width, 44.0f);
    _toolbar = [[UIToolbar alloc] initWithFrame:frame];
    [view addSubview:_toolbar];
 
    self.view = view;
    [view release];
    [_toolbar release];
}

This code reuses the screen setup already done by the content view controller, and re-layouts our subviews. It is a simple solution, and you will need a custom class for the root view with an overloaded layoutSubviews if you want to properly handle orientation changes. But I have left this out, as it is not within the scope of this post.

Next up we need to update the toolbar with contextual toolbar items, when our content changes. This is only supported if the content view controller is a UINavigationController, as can be seen in the initializer above. This could be made more flexible, but is also outside the scope of this post. We have set our toolbar controller to be the delegate for the content navigation view controller, so all we need to do is to respond to navigation events as they occur.

- (void)navigationController:(UINavigationController *)navigationController
        willShowViewController:(UIViewController *)viewController
        animated:(BOOL)animated;
{
    NSArray* items = nil;
    if ([viewController respondsToSelector:@selector(toolbarItems)]) {
        items = [viewController performSelector:@selector(toolbarItems)];
    }
    [_toolbar setItems:items animated:animated];
}

Conclusion

As shown with this code, doing the correct way with Cocoa Touch almost always means doing it in the easiest way as well. The hard part is knowing what the correct way is. My hope is that this post can guide you in the right direction. Rule of thumb is to always try to follow the same pattern as similiar things in Cocoa, it might feel like it is harder to do, but at the end of the day you will end up with less code, with more features.

The code above for implementing the custom toolbar controller, is much less code than what is needed to write a small application to demonstrate it being used. I have therefor made a small demonstration application with this complete code. It is a tree of table views, where each item opens up a new table view tree with one less toolbar item.

The source code is released under BSD license, and you can download it here.

The Anecdotal History

We are developing a custom application framework on top of MIDP, adding a MVC application model, and modern interface components with touch and animation support. All this is build on top of a shared subclass of Canvas, and our own custom drawing with screen transitions, etc. is implemented on top of that.

An interface component is called a View, and any interface component that can host other interface components implements the ViewParent interface. Simple until I introduces the method hasFocus(). All of a sudden the application refused to run on target Sony Ericsson device. The emulator worked nice, our P1i worked, even the Xperia X1 run. But none of the cybershots, or walkmans with JP-7 or JP-8.

"Application error". Oh well, that means that something threw an exception during the MIDlet constructor or appStart() call. So add pedantic catches, and display the error in an Alert; "NoClassDefFoundError".

The Problem

NoClassDefFoundError on the OSE phones, but no other installed with the same jad/jar-files, that is strange. Unfortunately Sony Ericsson has a policy of removing all error messages from exceptions, so no clue as to what class is missing either. Turn off Proguard optimization, still does not work, still NoClassDefFoundError. Head back to the Subversion logs and binary search, what is the latest revision that worked? And what was changed?

Turnes out that the shared Canvas subclass that implement the aforementioned interface ViewParent got the new method hasFocus(), and that is the only change from the working revision, to the broken revision.

- "I'm pretty sure that is working.", one of the half dozen bug-hunting team member said looking at:

public boolean hasFocus() {
    return true;
}

As it turns out the platform implementation of the MIDP class Canvas has a hidden method named hasFocus(). It is not private, but declared as public and final, but not exposed in the public API. So when our subclass is loaded, our public hasFocus() method clashes with the unexposed public final hasFocus() of the platform's implementation.

Solution, and Lesson Learned

The method hasFocus() was renamed to isInFocus(), and now everything works again.

From now on we will:

• Never trust subclasses of MIDP classes.
• Test on device early and often, also for obvious changes.
• Always keep commits small and atomic.

It is often nice to be able to reuse existing functionality when you subclass UITableViewCell. Properties such as image and textColor maps directly to the embedded UILabel and UIImageView subviews, and reimplementing them all when introducing a custom layout is tedious and error prone. Would it not be better to be able to get access to the original subview instances and just add a custom layout to them?

You can find subviews by class

Would it not be nice if the Cocoa Touch framework had a method such as this:

- (UIView*)viewWithKindOfClass:(Class)aClass;

Kind of like what viewWithTag:, does but instead of searching for a subview matching a tag, it searches for a subview matching a class.

Good news for us is that this is very easy to implement, by just adding a new category to UIView. Add a new .h/.m file pair to your Xcode project and type this down in the header file:

#import <UIKit/UIKit.h>
 
@interface UIView (CWViewWithKindOfClass)
 
- (UIView*)viewWithKindOfClass:(Class)aClass;
 
@end

Now we have to implement it. The existing viewWithTag: method is not documented as such, but my experimentation tells me that it uses a breadth first search algorithm. Quite logical as the wanted subview most commonly is close to the root view, and we want to find it fast. Since viewWithTag: always returns the first found matching view, we can do the same assumption.

The quite short implementation goes like this:

#import "UIView+CWViewWithKindOfClass.h"
 
@implementation UIView (CWViewWithKindOfClass)
 
- (UIView*)viewWithKindOfClass:(Class)aClass;
{
  NSMutableArray* nodeQueue = [NSMutableArray arrayWithObject:self];
  while ([nodeQueue count] > 0) {
    UIView* node = [nodeQueue objectAtIndex:0];
    [nodeQueue removeObjectAtIndex:0];
    if ([node isKindOfClass:aClass]) {
      return node;
    } else {
      [nodeQueue addObjectsFromArray:node.subviews];
    }
  }
  return nil;
}
 
@end

And that is it, not you can use it with something like for example this:

UITabBar* tabBar = [myTabBarController.view viewWithKindOfClass:[UITabBar class]];

Wich is an introduction to a future post, where I will discuss how to access the managed UITabBar of a UITabBarController, and introduce a UITabBarDelegate without interfering with the delegate already in place from the Cocoa Touch framework.

The four corners are coped as is, the four borders scaled in a single direction, and the center is scaled in both directions. Since MIDP do not support image scaling this must be implemented by hand using the ARGB values fetched using Image#getRGB(). The documentation is quite straight forward, but fail to mention one pecularity in many implementation...

Clearing unwanted data

I want to create the target image in a single int[] array to reduce memory usage. No problem copying image data into this structure, it is just what the quite straightforward API is designed to do:

public void getRGB(int[] rgbData,
                   int offset, int scanlength,
                   int x, int y,
                   int width, int height)

Unfortunately the documentation fails to mention that many implementations will not as expected just ignore data in rgbData that is not copied. Instead zeroes, or transparent pixels, will be filled in for any image data that has not been requested on a per row basis. I dare anyone to find where this is mentioned in the MIDP spec.

A solution

The solution is to write your own wrapper method for Image#getRGB() that copies just a single row of image data at a time, and the requested scanline length must be lied about to avoid having the remainder of lines filled with zeroes. Here is tho code ready for copy and paste:

public class ImageUtils {
    public static void getRGBFromImage(Image image, int[] argbData, int offset,
            int scanline, int x, int y, int width, int height) {
        for (int row = 0; row < height; row++) {
            image.getRGB(argbData, offset, width, x, y + row, width, 1);
            offset += scanline;
        }
    }
}

What you really want is to have the midlet write the log to your development PC instantaneously and free of charge, then you can log whatever you want to pinpoint your bug. This could be accomplished by logging over Bluetooth. Previously you had to write your own code to handle the logging and Bluetooth communication as well as a server to which the midlet connects and sends the log messages, but now there is a powerful logging framework for Java ME that offers this support out of the box. The framework is MicroLog and is open source under the Apache Software License, so it is free to use as you see fit. MicroLog can be configured with one or more appenders that takes care of the logging messages and sends them to the right destination and each appender can have its own formatter to format the messages appropriately. This is very similar to log4j, so if you have used log4j before, MicroLog is very easy to learn. If you are using Maven 2 you will be happy to know that MicroLog is built using Maven 2 and is available in a public repository.

Setting up MicroLog to use Bluetooth and log to your PC is simple. It only requires that you setup your Logger:

private final static Logger log = Logger.getLogger(TestMidlet.class);

and that you configure it to use a BluetoothSerialAppender, which is done like this:

log.addAppender(new BluetoothSerialAppender());

Now your midlet is all set to start logging over Bluetooth. For a full midlet example see the following code:

package se.jayway.me;

import javax.microedition.lcdui.Command;
import javax.microedition.lcdui.CommandListener;
import javax.microedition.lcdui.Display;
import javax.microedition.lcdui.Displayable;
import javax.microedition.lcdui.TextBox;
import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;

import net.sf.microlog.Logger;
import net.sf.microlog.bluetooth.BluetoothSerialAppender;

public class TestMidlet extends MIDlet
{

	private final static Logger log = Logger.getLogger(TestMidlet.class);

	public TestMidlet()
	{
		configureMicroLog();
	}

	protected void destroyApp(boolean arg0) throws MIDletStateChangeException
	{
		log.info("Destroying application...");
	}

	protected void pauseApp()
	{
		log.info("Pausing application...");
	}

	protected void startApp() throws MIDletStateChangeException
	{
		log.info("Starting application...");
		final TextBox textBox = new TextBox("Text", "My text", 100, 0);
		textBox.addCommand(new Command("Log", Command.SCREEN, 0));
		textBox.setCommandListener(new CommandListener() {
			private int counter;

			public void commandAction(Command c, Displayable d)
			{
				log.debug("You clicked " + counter++);
				log.debug(textBox.getString());
			}
		});
		Display.getDisplay(this).setCurrent(textBox);
	}

	private void configureMicroLog()
	{
		log.addAppender(new BluetoothSerialAppender());
	}
}

Build and deploy this midlet to your Bluetooth enabled device, supporting JSR-82, the Bluetooth API and make sure that Bluetooth is turned on.

Next you need to get the Bluetooth server that will receive and print the logging messages to standard out. The server is also available in a public Maven repository. Just download the version that ends with -jar-with-dependencies.jar. This file contains all its dependencies. Now make sure that your Bluetooth unit is on and discoverable on your PC. Then start the server with the following command:

java -cp microlog-servers-1.1.0-SNAPSHOT-jar-with-dependencies.jar net.sf.microlog.server.btspp.MicrologBtsppServer

You might have to change the jar file name if it is not the same as the one you downloaded, then just replace it with the file name of your own microlog-server jar file.

The server starts up and registers a logging service with a unique UUID that the phone will try to locate and connect to. Now start the midlet and see how it will start logging over the Bluetooth connection.

The first phone I tested was a SonyEricsson C905 and it worked perfectly from the start. Then I tried to use a SonyEricsson P990i and for some reason it failed to locate the logging server with the unique UUID. I was unable to determine the reason why it failed to locate the service, so instead I added support to the BluetoothSerialAppender to specify the url of the Bluetooth logger server. Using this and setting the server url to my PC it connected flawlessly to it and started logging. So if you experience problems when your midlet connects to the PC or if you are using multiple logger servers within the Bluetooth range of your device try specifying the server url that the BluetoothSerialAppender should connect to. The url of the server is shown when starting the logger server. This url does however contain a channel that is not possible to determine through the used API's, but it does start on 1 and increases. For each session I always got the same channel and it was only the next day that it changed and I got channel 2 instead, so try with 1 to start with and if that does not work increase it by one and try again. It will most likely work first or second time.

Now you are free to log as much as you want and do not have to restrict your logging during the development phase of your project. Neither is there a reason for writing your own Bluetooth logger, just use MicroLog.

The sessions are confidential so I will keep this post vague on the technical parts, not revealing any thing that might or might not come to an iPhone or iPod touch near you in the future. And I can not mention any specific sales numbers, but I do can say that any predicted numbers you might have seen; is probably an underestimation with a margin and then some.

The sessions where on a high level, not going too deep on technical details. Instead the sessions concentrated on the overall design philosophies, and common gotchas. For the nitty gritty details Apple engineers where available, and I missed half a session discussing the ins and outs of the UIToolbar class with Alberto Arauz. Alberto is one of the european software evangelist, and was most impressed, and interested, when I described the successful Mobile 2.0 track at Øredev 2008. Apple's overall impression with Scandinavia has so far been a mostly cold hand regarding anything with Apple, going as far as only six people registering for a Tech Talk in Oslo two years ago.

Apart from the speakers and engineers, Apple also brought a video-team. So yours truly has been intervjued about the applications I have on App Store, and my experience with the iPhone SDK. The video will be cut and edited for promotional purposes, and hopefully me mentioning both Malmö and Jayway will not be cut out. The odds of my short talk being included is quite good, as most developers seems to be focusing on games, not utilities as I and Jayway has done.

The best part to take home is not technical, just solid advice for any development, not even under NDA, and the sole point repeated by Apple over and over: Developing great applications is not about adding features! The trick is not to cram in as many features as you can, the trick is to know what features to leave out, so that time can be well spend on the key features that do make the cut. And this is tenfold as important on a mobile device where real estate is limited. A quote from Mark Twain:

I apologize for writing you a long letter, but I did not have the time to write a short.

Writing short, and cutting features is hard. How to decide on the features to drop or implement? Apple uses a simple technique, called a product statement. The product statement for the Photos application is for example; "An easy to use photo sharing application for all iPhone users". Any feature that do not help fulfilling this statement do not make it. How about simple photo-editing? Nope, does not comply with statement. The wording of the product statement is important, by simply changing it to "An easy to use photo sharing application for professional photographers", would be a completely new application. Only when the product statement is agreed upon, can an approved list of features be made. An omnipresent Steve Jobs approving and dismissing features, is an exaggeration, this simple method is what do the trick.

Now this might sound both obvious, and counterintuitive. Surely adding that last nice feature would add value? Not at the expense of a cluttered user interface, that is meant to be used while standing in line for 30 seconds. Features thought to be must haves, most of the time are not. Some features thought to be must haves are MMS and video recording. Looking at the raging success of the iPhone, it is very obvious that they are not must haves. We as software engineers must at long last learn that it truly is quality over quantity.

And lastly a personal reflection; from a developer's point of view the best part about iPhone SDK is that it is not an UI framework, it is an Application framework. It do not settle with providing the tools for collections, persisting data, displaying a UI, and then leave the rest of the architecture to the developers. The iPhone SDK supports all three parts of the Model-View-Controller paradigm equally well, and that is what makes it so productive.

Øredev was great success, especially all the people and the organization - a big Thank You to Michael and Emily for making this possible, you rock!

Now, it was really awesome to exchange Android games with Mike Jennings fro the Android team, and get him excited over the recent Android port to the Neo FreeRunner! Thanks Anders Hedberg for coming over to fix the FR, and to all the OpenMoko enthusiasts doing the hard work!

/peter neubauer

However, yesterday @Øredev, I met Mike Jennings from the Android team and together we looked into this problem over a beer in the Oracle booth. Looking into the current SVN source at http://svn.igniterealtime.org/svn/repos/smack/trunk/source, it seemed that a fast hack to get things working (especiallly the keystore problem on the device) would be to simply disable SSL negotiation.This does of course not work for SSL stuff, but it gets you going and it is enough for talk.google.com:5222. It is enough to just disable SSL negotiation by hardcoding it away in the ConnectionConfiguration.java, and comment out everything related to java.beans and other packages that are not present on the Android platform to get things working.

After doing that, voila things started to work and I am now happily logging in programatically via SVN Smack again!

Thanks Mike for the hints, help and a great BouncingBall application!

For anyone intersted, I am attaching the patch.

/peter neubauer

smackdiff

What is it?

The new Light Weight User Interface Toolkit (LWUIT) is a new UI toolkit for Java ME that is inspired by Swing. It is developed by Sun and it is available as open source (GNU GPL V2). The early access version runs on MIDP 2.0, but the upcoming versions will be available for other Java ME profiles as well. This opens up the possibility to write the same user interface code for mobile devices ranging from very simple mobile phones to advanced PDAs. The feature list for LWUIT is impressive. It includes features like:

• pluggable look-and-feels with themes
• layout managers
• touch screen support
• fonts
• resources bundles
• transitions
• 3D integration

The developer could create a customized look-and-feel by creating a subclass to
the LookAndFeel or DefaultLookAndFeel class, similar to Swing. On top of that it is possible to set a theme. A theme is defined in a Java property file. You use a key in the property file that is similar to a CSS selector. For example, Button. bgColor=ff0000 is used to set all button backgrounds to red.

The developer has access to layout managers like BorderLayout, FlowLayout,
GridLayout and others known from Swing. The GridBagLayout is not present, but I doubt that many will miss it. If you ever tried it, you know what I mean. The touch screen support is also an important feature, since many mobile devices today has touch screens.

The support for fonts in MIDP is rather limited. In LWUIT it is possible to use your own fonts. You use the resource editor to convert your fonts from your favorite operating system, and the selected fonts are converted and bundled in your jar file. The editor is also used for localization strings, images and themes.

A transition is used when switching between different forms, i.e. screens, and brings a nice touch to the UI. If the phone has an implementation of JSR-184:
Mobile 3D Graphics API for J2ME, it is possible to make a cube transition. The 3D integration let us show 3D models in our 2D interface. This is realized by loading an M3G file. The M3G format is 3D format that is optimized for Mobile
Devices (for more details see the references). By connecting each M3G object to a LWUIT graphic object it is possible to implement advanced logic for your 3D interface. The M3G is supported by JSR-184. A nice side effect of this is that the 3D graphics could be rendered by your 3D hardware on your mobile device. Support for SVG is also announced, which will give even more possibilities when writing UIs for mobile devices.

How to use it

And now for the moment you all have been waiting for. The code! We start with
the classical “Hello JayView” example. The code looks like this:

package se.jayway.javame.lwuit.test; 

import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException; 

import com.sun.lwuit.Button;
import com.sun.lwuit.Command;
import com.sun.lwuit.Display;
import com.sun.lwuit.Form;
import com.sun.lwuit.Label;
import com.sun.lwuit.animations.Transition3D;
import com.sun.lwuit.events.ActionEvent;
import com.sun.lwuit.events.ActionListener;
import com.sun.lwuit.layouts.BorderLayout;
import com.sun.lwuit.util.Log; 

public class HelloJayViewMIDlet extends MIDlet implements ActionListener { 

  private Command exitCommand;
  private Command nextCommand;
  private Form formTwo;
  private Button button; 

  protected void startApp() throws MIDletStateChangeException {
    Display.init(this); 

    Form formOne = new Form(”Hello”);
    formOne.setLayout(new BorderLayout()); 

    Label label = new Label(”JayView”);
    label.setAlignment(Label.CENTER);
    formOne.addComponent(BorderLayout.CENTER, label); 

    button = new Button(”Help Me”);
    button.addActionListener(this);
    formOne.addComponent(BorderLayout.SOUTH, button); 

    exitCommand = new Command(”Exit”);
    formOne.addCommand(exitCommand);
    nextCommand = new Command(”Next->”);
    formOne.addCommand(nextCommand);
    formOne.setCommandListener(this); 

    formOne.setTransitionOutAnimator(Transition3D.createCube(750, false)); 

    formTwo = new Form(”Hello Again”);
    // TODO: Add components and Commands to fromTwo
    formOne.show();
  } 

  protected void destroyApp(boolean unconditional)
      throws MIDletStateChangeException {
    // TODO: Add code that release all out resource
  } 

  protected void pauseApp() {
    // TODO: Do stuff when we pause the MIDlet
  } 

  /**
   * Implementation of the <code>ActionListener</code> interface.
   */
  public void actionPerformed(ActionEvent event) {
    Log.p(”actionPerformed()”, Log.INFO);
    Command command = event.getCommand(); 

    if (command == exitCommand) {
      notifyDestroyed();
    } else if (command == nextCommand) {
      formTwo.show();
    } 

    Object source = event.getSource();
    if(source == button){
      // TODO: Show some help to the user
    }
  } 

} 

At a first glance this looks like a normal MIDP application. You may recognize
Command, Form & Display classes. If you look close, you notice that these are
not the same classes. They are in fact classes found in the LWUIT toolkit and
actually work a little bit different. This is where the similarities end.

Let us take a look at the differences instead. We start by initializing our display
with Display.init(). This takes a reference to our MIDlet object, which in turn
takes care of all the initialization. We continue by creating a Form object which
occupies the whole screen. The Form object is populated with a Label that
is placed in center of the screen. The alignment of the label is set to center.
As you can see we have good control of the placement of our components,
unlike MIDP where you are dependent on the underlying implementation. A
Label object can have a text and/or an icon. When we have both, it is of course
possible to align the text relative to the icon.

A Button object is like a button that you are used to from your desktop
applications. However it is something that is not found in MIDP. Just
like a Label you could have an icon and/or a String in each Button. You
add an ActionListener to the Button, which in our case is the MIDlet that
implements the ActionListener interface. The ActionListener consists of the
actionPerfomed() method, which is like Swing, not like MIDP. The Button is
added to the south of the Form. It occupies the whole width of the Form since
that is how BorderLayout works like. In a real world example we could use
nested layouts to fix this problem. It should be noted that there are still some
peculiarities in this early access release. For example it is possible set the colors
of a Label object, but not on a Button object.

The next thing to do is to create our Command objects. Each Command
object corresponds to an item in one of the menus. We add them to the Form.
The action could be the user pressing a button or selecting a command. The
Command that triggered a call to actionPerformed() is fetched using the event.
getCommand() method. We use an if-else statement to check which Command
that was used. If you have more Command objects than this, you should consider
using the Command pattern as described in JayView 10, Take Command in
Java ME. We must also check if the event was received from the button. We
get the source with a call to event.getSource(), just like in Swing. We finish off
the actionPerformed() method by checking if the event was received from our
button.

In our example we call notifyDestroyed() to signal to the platform that we are
finished. In the other case we show our second Form. By the way, did you notice
that we did call a method called setTransitionOutAnimator()? This is used to
create a 3D cube transition when switching between the first and the second
Form. It is not something that is available in MIDP.

The LWUIT toolkit contains some utilities like a logging utility, as seen in
actionPerformed(). This is an easy way to do some simple logging. But I would
recommend that you use a proper Java ME logging framework, like Microlog.

Voila! This is how it looks like in an emulator.

Some Final Words

My first impression of LWUIT was very positive. Since I consider myself a fluent
writer in “Swinglish”, I was happy when I could re-use my programming skills
for LWUIT. Many Swing lovers will have the same feeling, I guess. Since it is
open source I think that the toolkit could reach a wide audience and hopefully
it will have a large community with all its benefits. A big advantage is that we
now have a large set of components available. One thing missing in MIDP is
a tabbed pane, which is included in LWUIT. Another thing to consider is of
course the size that the LWUIT adds to your application. The full size of the
jar-file is about 230 KB. In practice you will not use all the classes, and with
an obfuscator the size will be reduced even further. According to the LWUIT
development team the average overhead when using LWUIT is around 100 KB.
In any case an obfuscator should always be part of your Java ME toolbox.

On the downside is the performance. I have tested it on a Sony Ericsson W910,
which contains a high performance JVM. Although some of the components
were not as fast as I would like them to be it has to be pointed out that this is
only an early access release and the performance will probably be much better.
Another possible disadvantage is the type of open source license that has been
chosen. Many people would argue that the Apache License would be a better
license. However this is a minor issue.

I think that this could be a practical alternative when developing MIDP
applications. Its success depends on the performance and a large developer
community. If both of these get satisfied we will see many mobile applications
developed with LWUIT, at least according to my opinion.

References