Cocoa, and by inheritance Cocoa Touch on iOS makes a clear distinction between what is an exception, and what is an error in your application. This should be obvious since NSException and NSError both inherit from the NSObject root class with no relations at all.
Programmer vs. User
Exceptions are intended for signaling programming errors and fatal errors that the application can never recover from. One such error is index out of bounds when accessing an array. There is little reason to catch any exception; if you for example could not calculate a legal array index the first time around your app is in an illegal state. Exceptions are for your own use as a developer, to catch all programming errors in testing before shipping to the end user. Only secondary to inform the user of fatal errors when possible.
Errors are intended for signaling user errors, and conditions that can not be predicted until the end user runs your application. One such error is network timeout. There are many reasons to catch these errors; e.g. the user could be asked to check the network connectivity, and try again. Errors should always be handled, and be properly presented to the user. A user is much more forgiving if your application fails with a clear reason, than if it simply crashes or refuses to work.
Signal and Handle Exceptions
Exceptions are thown in Objective-C, just as in most other programming languages. You can construct your NSException object manually, and throw it using the @throw compiler directive if you like. But the preferred way is to use the NSExceptionconvenience class methods.
|
1
2
|
[NSException raise:NSInvalidArgumentException
format:@"Foo must not be nil"];
|
Here we see the first divergence from how for example Java and C# handles exceptions. In Objective-C different exceptions are not normally signaled by different subclasses, but instead the exception is given a name, in the form of a constant string. Exceptions are however handled quite traditionally.
|
1
2
3
4
5
6
7
8
9
|
@try {
// Normal code flow, with potential exceptions
}
@catch (NSException* e) {
// Handle exception or re-throw
}
@finally {
// Mandatory cleanup
}
|
Signal and Handle Errors
Errors do not use any special feature of the Objective-C run-time or programming language. Errors are instead treated as normal method arguments.
For synchronous tasks the error is returned as the last out argument of the method. A typical synchronous method signature with error handling looks like this:
|
1
2
|
- (id)initWithContentsOfURL:(NSURL *)url
error:(NSError **)outError
|
The client of such a task can always pass NULL to explicitly ignore the details of the error, the method must therefor also signal the error by the return value. This is typically done by returning nil, or NO if no other return value should exist. Ignoring the error is never recommended.
For asynchronous tasks the error is returned as the last argument of a delegate method. A typical asynchronous method signature with error handling looks like this:
|
1
2
|
- (void)connection:(NSURLConnection *)connection
didFailWithError:(NSError *)error
|
The client of such a task can never opt out of receiving the error. It is still never recommended to ignore the error.
The information in an NSError is always localized and phrased in end-user friendly words. This is something you can trust of errors from system frameworks, and a hard requirement on you when you create your own errors. Therefor handling the error is never a burden, in the simplest case you can simply display the localized error message to the end user and call it a day.
|
1
2
3
4
5
6
7
8
9
|
- (void)connection:(NSURLConnection *)connection
didFailWithError:(NSError *)error
{
[[[[UIAlertView alloc] initWithTitle:[error localizedDescription]
message:[error localizedFailureReason]
delegate:nil
cancelButtonTitle:NSLocalizedString(@"OK", nil)
otherButtonTitles:nil] autorelease] show];
}
|
There is more to NSError
Cocoa and Cocoa Touch have much in common. Classes not brought straight over from Mac OS X to iOS often have a sibling anyway. One such class is NSAlert from Mac OS X and it’s sibling UIAlertView on iOS. They serve the same purpose of displaying an alert message to the end user, optionally with a few choices in the form of buttons.
One convenience method for handling errors on Mac OS X is -[NSAlert alertWithError:], it did not survive the transformation to UIAlertView on iOS. It is a pity, since it is a convenient way to quickly setup an alert with all the localized and human readable information. Basically turning the example code for handling an asynchronous error above from five lines of code, into a single line of code.
But that is not all. NSAlert and NSError on Mac OS X also have standardize facilities for handling recovery options. For example adding a “Retry” button to the alert, and calling the correct methods in response to this user selection.
On iOS NSError still have all the facilities to handle error recoveries, it is only UIAlertView that is lacking the final user facing bits. Fortunately this is easy to add. NSError manages error recovery with information held in it’s userInfo dictionary. The following keys are used:
NSLocalizedRecoverySuggestionErrorKey– A localized text with a general suggestion for how to recover from the error, for example “Check the network connection”.NSLocalizedRecoveryOptionsErrorKey– An array of localized button titles such as “Retry”.NSRecoveryAttempterErrorKey– An object conforming to the informal protocolNSErrorRecoveryAttempting.
The informal protocol NSErrorRecoveryAttempting declares one method that is significant for iOS:
|
1
2
|
- (BOOL)attemptRecoveryFromError:(NSError *)error
optionIndex:(NSUInteger)recoveryOptionIndex
|
The recoveryOptionIndex is the index into the array of button titles, and is the actual choice the user made for recovering from the error.
Adding a -[UIAlertView alertWithError:] convenience method to UIAlertView is made really easy since Objective-C has categories, and classes themselves are object instances so we can use the UIAlertView class as alert delegate for error recovery alerts.
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
|
@implementation UIAlertView (CWErrorHandler)
static NSMutableDictionary* cw_recoveryErrors = nil;
+(void)alertViewCancel:(UIAlertView *)alertView;
{
NSValue* key = [NSValue valueWithPointer:(const void *)alertView];
[cw_recoveryErrors removeObjectForKey:key];
}
+ (void)alertView:(UIAlertView *)alertView
clickedButtonAtIndex:(NSInteger)buttonIndex;
{
NSValue* key = [NSValue valueWithPointer:(const void *)alertView];
NSError* error = [cw_recoveryErrors objectForKey:key];
NSString* buttonTitle = [alertView buttonTitleAtIndex:buttonIndex];
NSInteger recoveryIndex = [[error localizedRecoveryOptions]
indexOfObject:buttonTitle];
if (recoveryIndex != NSNotFound) {
[[error recoveryAttempter]
attemptRecoveryFromError:error
optionIndex:recoveryIndex];
}
[cw_recoveryErrors removeObjectForKey:key];
}
+(UIAlertView*)alertViewWithError:(NSError*)error;
{
UIAlertView* alert = [UIAlertView alloc];
[[alert initWithTitle:[error localizedDescription]
message:[error localizedFailureReason]
delegate:nil
cancelButtonTitle:NSLocalizedString(@"Cancel", nil)
otherButtonTitles:nil] autorelease];
if ([error recoveryAttempter]) {
if (cw_recoveryErrors == nil) {
cw_recoveryErrors = [[NSMutableDictionary alloc]
initWithCapacity:4];
}
NSValue* key = [NSValue valueWithPointer:(const void *)alertView];
[cw_recoveryErrors setObject:error
forKey:key];
for (id recoveryOption in [error localizedRecoveryOptions]) {
[alert addButtonWithTitle:recoveryOption];
}
alert.delegate = (id)self;
}
return alert;
}
@end
|
Conclusion
The clean separation of exceptions and errors help you as a developer to catch programming errors during development and with unit tests, and also handle errors of interest to the end users in a standardized and uniform way. The very nature of NSErrorencourages developers to write descriptive error messages that end users can understand and make informed discussions about. Errors are unavoidable in any application of non-neglectable complexity, gracefully handling these errors gives an aura of quality and ensures happy users. Happy users means better sales.
Full source code to the examples in this post, including some more convenience methods can be downloaded here, and are released under the Apache 2 open source license.