Modal View Controllers are Easy

Displaying a modal view controller is quite straight forward as this small example shows:

-(void)showDetails:(CWDetails*)details {
  UIViewController* vc = [[CWDetailsViewController alloc] initWithDetails:details];
  [self presentModalViewController:vc animated:YES];
  [vc release];
}

Popover View Controllers Can be Complex

Displaying the same details view controller in a popover on iPad is not quite as straight forward:

-(void)showDetails:(CWDetails*)details fromBarButtonItem:(UIBarButtonItem*)item {
  UIViewController* vc = [[CWDetailsViewController alloc] initWithDetails:details];
  self.popoverController = [[[UIPopoverController alloc]
                                  initWithContentViewController:vc] autorelease];
  self.popoverController.delegate = self;
  [self.popoverController presentPopoverFromBarButtonItem:item
                                 permittedArrowDirections:UIPopoverArrowDirectionAny
                                                 animated:YES];
  [vc release];
}

-(void)popoverControllerDidDismissPopover:(UIPopoverController*)popoverController {
  self.popoverController = nil;
}

As you see presenting a popover requires an extra object instance, this instance is not automatically retained while presenting the popover, like a modal view controller is, so the instance must be saved somewhere. In this example I saved the instance as a property. Notice that I also register as a delegate for the popover in order to remove this instance when the popover is dismissed. Here is another detail that is not obvious; this delegate callback is only called if user action dismisses the popover, not if you programmatically dismiss the popover. In the end using popovers quite quickly introduces a lot of code, and also coupling between view controllers for no other reason but to manage the popover instance.

Would it not be nice if you could instead do like this, and be done with it:

-(void)showDetails:(CWDetails*)details fromBarButtonItem:(UIBarButtonItem*)item {
  UIViewController* vc = [[CWDetailsViewController alloc] initWithDetails:details];
  [self presentPopoverViewController:vc fromBarButtonItem:item animated:YES];
  [vc release];
}

In fact what we want is to have these methods added to the public API of UIViewController:

@interface UIViewController (CWPopover)

@property (nonatomic, retain, readonly) NSSet* visiblePopoverControllers;

-(void)presentPopoverViewController:(UIViewController*)controller
                  fromBarButtonItem:(UIBarButtonItem *)item
                           animated:(BOOL)animated;
-(void)presentPopoverViewController:(UIViewController*)controller
                           fromView:(UIView *)view
                           animated:(BOOL)animated;

-(void)dismissPopoverController:(UIViewController*)controller animated:(BOOL)animated;
-(void)dismissAllPopoverControllersAnimated:(BOOL)animated;

-(void)setContentSize:(CGSize)size forViewInPopoverAnimated:(BOOL)animated;

@end

But That Requires Rewriting Existing Classes?

Yes it does, in an ideal world we want new methods and properties on the existing UIViewController class, and all subclasses, just as if Apple had put them there. This can easily be done thanks to the dynamic nature of Objective-C.

The view controller that is going to present other view controllers in a popover needs to have access to all UIPopoverController instances currently visible. The view controllers that are going to be presented in a popover need to have access to their container UIPopoverController, and for consistency with modal view controller its parent view controller.

Categories can only add and replace methods on an existing class, not modify instance variables. So we need to store this information in another way. I choose to tuck them away in a helper class called CWViewControllerPopoverHelper. With this small interface:

@interface CWViewControllerPopoverHelper : NSObject {
@private
    UIViewController* parentViewController;
    UIPopoverController* containerPopoverController;
    NSMutableSet* visiblePopoverControllers;
}
@property (nonatomic, assign) UIViewController* parentViewController;
@property (nonatomic, assign) UIPopoverController* containerPopoverController;
@property (nonatomic, retain) NSMutableSet* visiblePopoverControllers;

@end

The implementation is just synthesized properties, so no need to duplicate that one here.

So now all we do is to stuff one instance of CWViewControllerPopoverHelper into a global map using the UIViewController as key for each view controller that needs these extra instance information.

Fetching the Popover Helper

Let's implement a helper method that lazily creates a CWViewControllerPopoverHelper instance and puts it into the global map when needed. This way any view controller that do not need to support popovers will never be bothered, and those who do manage popovers gets one instance with no fuzz:

static NSMutableDictionary* popoverHelpers = nil;

-(CWViewControllerPopoverHelper*)popoverHelper;
{
    NSValue* key = [NSValue valueWithPointer:self];
    if (popoverHelpers == nil) {
        popoverHelpers = [[NSMutableDictionary alloc] initWithCapacity:16];
    }
    CWViewControllerPopoverHelper* helper = [popoverHelpers objectForKey:key];
    if (helper == nil) {
        helper = [[[CWViewControllerPopoverHelper alloc] init] autorelease];
        [popoverHelpers setObject:helper forKey:key];
    }
    return helper;
}

Proper Memory Management

There is one problem with storing the extra information in a global map; no view controller would ever be released from memory, since the map will hold on to the references. No problem, lets not use the actual view controller instance as a key, but a NSValue with the pointer to the instance. This solves the problem of releasing objects, but also means that the map will contain dangling pointers to released objects. We need to remove the dangling pointers whenever a UIViewController is deallocated.

Subclassing is not an option, since it would defeat our purpose of requiring the public API. It turns out we can replace the -[UIViewController dealloc] method with our own, and still call the original implementation. Each class and category that is loaded into the Objective-C run-time will call their own method +[? load] method, it is the public hook for further modifying a class or category before use. We want to use this hook to replace the default deallocation method with our own:

+(void)load;
{
    Method m1 = class_getInstanceMethod(self, @selector(dealloc));
    Method m2 = class_getInstanceMethod(self, @selector(cwPopoverDealloc));
    method_exchangeImplementations(m1, m2);
    m1 = class_getInstanceMethod(self, @selector(parentViewController));
    m2 = class_getInstanceMethod(self, @selector(cwPopoverParentViewController));
    method_exchangeImplementations(m1, m2);
}

As a bonus we also replace -[UIViewController parentViewController], to return the parent as would be expected for anyone who has ever presented a modal view controller. The implementations of our overrides are just as short and sweet:

-(void)cwPopoverDealloc;
{
    [self dismissAllPopoverControllersAnimated:NO];
    NSValue* key = [NSValue valueWithPointer:self];
    [popoverHelpers removeObjectForKey:key];
    [self cwPopoverDealloc];
}

-(UIViewController*)cwPopoverParentViewController;
{
    UIViewController* parent = [self popoverHelper].parentViewController;
    if (parent == nil) {
        parent = [self cwPopoverParentViewController];
    }
    return parent;
}

Wrapping Up

From here on it is just a tedious work to implement all 50 more lines of code needed to actually present the popovers, the first method as an example:

-(void)presentPopoverViewController:(UIViewController*)controller
                  fromBarButtonItem:(UIBarButtonItem *)item
                           animated:(BOOL)animated;
{
    UIPopoverController* pc = [[[UIPopoverController alloc]
                                initWithContentViewController:controller] autorelease];
	[self addPopoverViewController:pc passthroughViews:views];
    [pc presentPopoverFromBarButtonItem:item
               permittedArrowDirections:UIPopoverArrowDirectionAny
                               animated:animated];
}

The rest of the implementation, and a few other nice to have methods can be downloaded here.

Conclusions

The dynamic nature of Objective-C means that you can rewrite any existing API to suit your needs, without having access to the original source code. Sometimes just to add a new utility function where it belongs; a "sort by first name" method should probably be added to the actual people collection class, not as a spurious utility class.

Or as shown in this example to make a public API more convenient to use.

Here is a list of useful facts before we throw ourselves into the code.

• Open Source Apache 2 library
• Hosted at Google Code: http://google-collections.googlecode.com/
• Requires Java 1.5
• 1.0 Release Candidate 3 now
• 25,000 unit tests
• Used by Google in production

Immutable Collections

A big part of the collections library is focused on immutability, the reason for this is the increased demand for concurrent code in order to be able to utilize the ever increasing number of cores in modern computers.

Immutable data are thread-safe because it can never be changed and can therefore be shared between multiple threads without worrying. This is a huge improvement because of the complexity involved writing thread safe code that uses mutable data. furthermore immutable data can be handed to untrusted code without worrying about the data being changed by the untrusted code, this really helps sustaining the security boundaries of your system.

Another benefit of using immutable collections is that they are in most cases more memory efficient and perform better than the regular collections.

In a way it was also possible to create immutable collections with the standard Java API, as an example a set could be made immutable the following way:

 
Set<Integer> numbers = new TreeSet<Integer>(Arrays.asList(0,1,2,3,4,5,6,7,8,9));
Set<Integer> immutableNumbers = Collections.unmodifiableSet(numbers);
 

With Google Collections it would look the following way:

 
ImmutableSet<Integer> immutableNumbers = ImmutableSet.of(0,1,2,3,4,5,6,7,8,9);
 

There are several things that are better in the version using Google Collections. You only need to know about the ImmutableSet class, where as in the standard Java version, four classes are combined to achieve the same effect, that is just confusing. When using the new keyword to construct generic classes, the generic type can't be inferred from the constructor arguments, this limitation is not present for methods. Google Collections uses static factory methods to create their collections meaning the generic type will be inferred in this case and therefore turning the code noise down. The third benefit is that the immutable collections are guaranteed to be immutable where as an unmodifiable collection is just an immutable view of the collection and can be changed by code holding a reference to the actual collection. The last benefit is that the information about immutability is captured in the type and clients of this type therefore will be able to count on that the collection is immutable, which means that defensive copying is unnecessary. Be aware that it is only the collection that is promised to be immutable, if the objects contained in the collection are not immutable they can still be changed. Notice that ImmutableSet implements the Set interface so it can be used seamlessly with existing code.

Those of you who are familiar with functional programming languages, may expect, that mutating methods like add returns a modified copy of the collection. But in order to implement the standard Java collections interfaces, this is not possible, so instead they just throw an exception. You can of cause still combine existing immutable collections into new ones. If you for example want to create the union of two sets, you can do it the following way:

 
ImmutableSet<Integer> lowNumbers = ImmutableSet.of(0,1,2,3,4,5,6,7,8,9);
ImmutableSet<Integer> highNumbers = ImmutableSet.of(5,6,7,8,9,10,11,12,13,14,15);
SetView<Integer> union = Sets.union(lowNumbers, highNumbers);
 

Notice how we use the static union method on the Sets class to create a new SetView based on the two given sets. The SetView is an unmodifiable implementation of the standard Set interface but can change if the underlying collections changes. Google Collections provide similar convenience classes for working with all the popular collections interfaces from the standard Java API, improving your productivity a lot.

Numerous immutable collections exist in the library, for more information see the API documentation.

New collections types

Google Collections also provides implementations of a few collections that is not included in the standard Java. These collections can be very useful in special cases.

Multisets

Multiset is a very useful collection for collecting statistic data of some kind. The collection is basically just a set where a count of how many instances has been added of each element is maintained. So if we as an example want to count the occurrences of each number in a list of numbers it can be done the following way.

 
ImmutableList<Integer> numbers = ImmutableList.of(2,3,0,1,0,1,2,3,2,3);
Multiset<Integer> multiset = TreeMultiset.create(numbers);
multiset.remove(0); // Decreasing the count for 0 by 1
multiset.add(1, 4); // Increasing the count for 1 by 4
 

The resulting multiset after adding the list of numbers contains to following information:

• 0 has 1 occurrences
• 1 has 6 occurrences
• 2 has 3 occurrences
• 3 has 3 occurrences

Numerous implementations of the Multiset exists, so it is a good idea to match your requirement against the capabilities of the different implementations before choosing one.

Multimaps

Have you ever implemented a Map where each key could be associated to a list of values - that's exactly what a Multimap is. This is useful in many cases, for example indexing. To show the functionality I'll index fruits by colors. The Fruit class is just a class with a name and a color and the fruits collection contains banana, strawberry, cucumber, kiwifruit, tomato and lemon. First we create a new multimap for the color index, then we look through all the fruits and add them to the color index using the color of the fruit as index. After we have constructed the index, we get a collection of red fruits using the get method. And finally, we assert that a tomato is a red fruit.

 
Multimap<Color, Fruit> colorIndex = HashMultimap.create();
for (Fruit fruit : fruits) {
    colorIndex.put(fruit.getColor(), fruit);
}
Collection<Fruit> redFruits = colorIndex.get(Color.RED);
assertTrue("Tomato is a red fruit", redFruits.contains(TOMATO));
 

BiMap

A BiMap is an implementation of a bidirectional map, that is a map where a one-to-one relation between each key and value exists. The BiMap is special because it is capable of producing the inverse mapping using the inverse method. Bidirectional maps are also useful for indexing in cases where an one-to-one relationship exists and you don't want the relationship encoded in the objects. As an example we will look at mapping numbers to their names and back again.

 
ImmutableBiMap<Integer, String> biMap = ImmutableBiMap.of(0, "Zero", 1, "One",
        2, "Two", 3, "Three");
assertEquals("2 should be mapped to Two", "Two" , biMap.get(2));
 

We can easily create a mapping between the numbers and their names using the of method on the ImmutableBiMap implementation. As with the Multisets and Multimaps numerous implementations exists to fit your exact needs.

For a BiMap we can get the inverse BiMap the following way:

 
BiMap<String, Integer> inverseBiMap = biMap.inverse();
assertEquals("Two should be mapped to 2", Integer.valueOf(2),
        inverseBiMap.get("Two"));
 

Ordering

If you ever have struggled with implementing Java's Comparator interface the Ordering class from Google Collections is you friend. The Ordering class provides you with everything you need for handling ordering of collections. Furthermore the Ordering class implements the Comparator interface to handle backwards compatibility. If you, for example, want to sort the fruits earlier mentioned first by color then by name it can be done the following way.

 
Function<Fruit, Color> getColorFunction = new Function<Fruit, Color>() {
    public Color apply(Fruit from) {
        return from.getColor();
    }
};
 
Function<Fruit, String> getNameFunction = new Function<Fruit, String>() {
    public String apply(Fruit from) {
        return from.getName();
    }
};
 
Ordering<Fruit> colorOrdering = Ordering.natural().onResultOf(getColorFunction);
Ordering<Fruit> nameOrdering = Ordering.natural().onResultOf(getNameFunction);
 
Ordering<Fruit> colorAndNameOrdering = colorOrdering.compound(nameOrdering);
 
ImmutableSortedSet<Fruit> sortedFruits = ImmutableSortedSet.orderedBy(
        colorAndNameOrdering).addAll(fruits).build();
 
System.out.println(Joiner.on(", ").join(sortedFruits));
 

Prints out:

Green Cucumber, Green Kiwifruit, Red Strawberry, Red Tomato, Yellow Banana,
Yellow Lemon

First I create the ordering of fruits by color. The Color enumeration implements Comparable, so we just want to promote the ordering of fruits to use the natural order of the Color class. To do this we create a natural order on the result of the function that retrieves the color from a fruit. To verify that the ordering works, I create a new ImmutableSortedSet with the ordering we just created and print the result. Notice that it is necessary to used the builder pattern in order to create the ImmutableSortedSet with a specified order.

The ordering on fruit names is similar to the way we order by colors except we use a function that retrieves the name of the fruit.

When we have the two orderings we can make a compound ordering by using the compound method on the ordering that should be applied first. A compound ordering applies each ordering in turn to achieve a hierarchical ordering. In this case the color-ordering is first applied, if the objects are equal, according to that ordering, the naming-ordering is applied.

Another use case of the Ordering class is sorting Iterable classes where elements are not guaranteed to be unique. Normally you would have to first convert the iterable to a list and then use the sort method on the Collections class to sort the elements. Consider the case of sorting an iterable of numbers in reverse order, this can be done the following way in standard Java:

 
List<Integer> sortedNumbers = new ArrayList<Integer>(numberIterable);
Collections.sort(sortedNumbers, Collections.reverseOrder());
 

The same result can be achieved with Google Collections the following way:

 
List<Integer> sortedNumbers = Ordering.natural().reverse().sortedCopy(numberIterable);
 

This doesn't seem like a big difference. But in the standard Java example involves three different classes and the generics is specified two times.

Iterables and Iterators

Iterables and iterators are a powerful abstraction that lets you handle streams of data in an uniform way. But the standard Java library doesn't provide you with many tools to handle these types. Google Collections includes two classes with several convenience methods to work on these types. The two classes contains the same methods so I'll only focus on iterables.

Imagine that you are given an iterable of numbers should find all the even numbers, square them and return a new iterable of the result. Of course this should be done without reading all the numbers in the given iterable. In standard Java you would need to implement two iterators and two iterables in order to achieve this. In Google Collection it can be done the following way:

 
Predicate<Integer> evenPredicate = new Predicate<Integer>() {
    public boolean apply(Integer input) {
        return input % 2 == 0;
    }
};
 
Iterable<Integer> evenNumbers = Iterables.filter(numbers, evenPredicate);
 
Function<Integer, Integer> squareFunction = new Function<Integer, Integer>() {
    public Integer apply(Integer from) {
        return from * from;
    }
};
 
Iterable<Integer> squareOfEvenNumbers = Iterables.transform(evenNumbers,
        squareFunction);
 

First we create a predicate function that only accepts even numbers and filters the given numbers by this predicate function. Notice this is done lazily so the original iterable is not touched, which means at no time is a collection containing all the results constructed and stored in memory. All the methods on Iterables and Iterators classes is as lazy as possible.

Then we create a square function and apply it to the iterable of even numbers giving us a new iterable with the squared even numbers.

It is important to understand that the predicate and square functions will first be applied when the iterable is used to iterate through the squared even numbers.

Conclusion

In my opinion Google Collection will definitely improve your code, making it more readable and save you from creating your own error-prone implementation of the functionality already provided and tested by Google. I think that it is especially good that the library extends the standard library in a non intrusive way, instead of creating a parallel collection library. This also means that you can choose to use only the convenience classes and not spreading Google specific types all over your system if that worries you.

Usability is the science of usage which means that usability rules and laws apply to rich clients, web applications, paper forms, furniture, milk cartons, tools etc. It needs to be taken into consideration whenever there is a human end-user. If not, the product will be designed to be specifically useful to the designer.

Know your user

The first question to ask yourself is: Who is going to use your API? If you know that
then you are half way to the bank. Why? Simply because you know what your users
know and want, and thus you can give them what they need.
If the user has a list of objects and wants to remove objects which already exists in
another list, your API could look something like this:

CustomList myList = getMyList();
CustomList yourList = getYourList();
myList.removeSharedItems(yourList);

“myList.removedSharedItems(yourList);” describes what the function does to your
list, and is suited for most any programmer. If, on the other hand, you know that
your users are working with set theory, you would probably want to do something
like this:

CustomList myList = getMyList();
CustomList yourList = getYourList();
myList.toRelativeComplement(yourList);

Let the API be self-documenting

Remember that when it comes to learning or getting started with an API, many pro-
grammers simply rely on the AutoCompletion-function in their IDE. If they don’t
get it from looking at that, they might turn to the documentation, or simply turn to
another competing API. So don’t take naming your classes and methods lightly.
In the previous example both

myList.removeSharedItems(yourList);

..and:

myList.toRelativeComplement(yourList);

..mutate myList. This is visualised by using “remove” and “to” which both refer
to the myList-object. If for example “myList.toRelativeComplement (yourList);”
didn’t have the word “to”, the user wouldn’t know if it returns the relative comple-
ment or if it mutates myList to it.
In SpringFramework, self-explanatory class names such as “BatchPreparedState-
mentSetter” (an interface for a prepared statement setters used during batch up-
dates) are widely used. The only risk with this is that class-, interface- and method
names can get rather long, resulting in poorer readability. Explain what it does but
be as precise as possible and don’t take it to the extreme.

Don’t present the underlying implementation

The API should limit itself to what the user needs to know; no more, no less. The
names of classes, interfaces and methods should describe what they do and what
they are used for; not how they do it. Why force the user to know what the underly-
ing implementation does if they don’t need to know? Open-source your code and
give the user the choice to see how it is done instead of forcing it on them.
Java.io.Properties.loadFromXML takes an InputStream. This means that to load
properties from XML the following needs to be done.

File myProps = new File(“.\\MyProps.xml”);
FileInputStream is = new FileInputStream(myProps);
Properties p = new Properties();
//void loadFromXML(InputStream in)
p.loadFromXML(is);

The fact that loadFromXML takes an InputStream describes what the method does.
A better solution would be to look at SpringFramework’s Resource solution. There
they have a common interface called “Resource” which is implemented by every-
thing from FileSystemResource to InputStreamResource. If java.io.File were to im-
plement such an interface, a solution could simply be:

Properties p = new Properties();
//void loadFromXML(Resource xmlResource)
p.loadFromXML(new File(“.\\MyProps.xml”));

In this case the user of the API doesn’t have to think about in what way the XML
will be read; just that it will be read.

Think of logical mapping

The methods of a class (name and responsibility) must map well to the classes
name; input and output of a method must map the responsibility of the method and
so on. If this is done, the user will be able to use the API intuitively, and learn and
understand how to use it without any documentation.

//Bad mapping in Calendar
void setTime(Date date)
//Better mapping
void setTime(Time time)

Limit the number of options

If you have something in your API that can be done in two different ways, choose
one. Don’t give the user an ambiguous API with features that are so similar that it is
confusing, and force them to go to the documentation or choose by chance.

myCalendar.add(Calendar.DAY_OF_WEEK,7);
//...differs from...
myCalendar.roll(Calendar.DAY_OF_WEEK,7);
//...in what way?

Avoid methods and classes that do
different things in different object states

Separate your domain entities in such a way that they overlap as little as possible.
This is basic OO and should be common sense, but it is a common problem. Java.
io.File has exactly this problem. An object of java.io.File can be a File or a Directory.
If the object is created from the path of a directory it is a directory. This gives the
possibility to write, among other things, the following illogical code:

File myFile = new File(“.\\MyFile.xml”);
boolean dirMade = myFile.mkDir();

A better solution would be if File were structured something like:

interface FileSystemElement extends Resource{
   //...
}
class abstract AbstractFileSystemElement implements FileSystemElement{
   //...
} 

class File extends AbstractFileSystemElement{
   //...
} 

class Directory extends AbstractFileSystemElement{
   //...
} 

Summary

The most important thing to remember is that there is a human user at the other
end of an API. If you remember this you will create better APIs. The pointers in this
article simply scratch the surface of what could be done to improve your APIs. One
thing that would result in great improvements is if you found a couple of users and
user-tested the solution. (http://en.wikipedia.org/wiki/Usability_testing).

Originally published in JayView.