Core Data and Enterprise iPhone Applications – Protecting Your Data

It has always been a difficult question and fortunately Apple has addressed it for us. Even better, Nick has shared the code so we don’t even need to try and discover the solution ourselves.

Thanks Nick!

Download the source code for the Favorite Things project.

A Few of My Favorite Things

My kids have been watching The Sound of Music lately, but that’s not what made me decide to use a list of favorite things as the premise of my example code (sorry if that just got a Julie Andrews song stuck in your head. For the rest of you who have no idea what I’m talking about, move along. Nothing to see here). What made me think of it is the fact that your favorite things might need re-ordered from time to time. A list of my favorite things all seem to be Apple products as the example code shows. Yours might be something else. I’ve added a method at the start of this example app to populate the Core Data database with a list of a few of my favorite things (“♫♫…when the dog bites, when the bee stings, when you’re feeling sad ♫♫… ooops, sorry). I first fetch the list and if it’s empty I go ahead and populate the Core Data data store. Here is that code:

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

- (void)loadFavoriteThingsData;
{
  if ([[fetchedResultsController fetchedObjects] count] > 0)
    return;
 
  NSManagedObject *favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"MacBook Pro" forKey:@"thingName"];
  [favoriteThing setValue:@"A powerful computer that will burn your lap." forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:0] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"iPad" forKey:@"thingName"];
  [favoriteThing setValue:@"That's a really big iPod!" forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:1] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"iPhone" forKey:@"thingName"];
  [favoriteThing setValue:@"A computer that thinks it's a phone." forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:2] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"iPod" forKey:@"thingName"];
  [favoriteThing setValue:@"Also known as the iPad nano." forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:3] forKey:@"displayOrder"];
 
  favoriteThing = [NSEntityDescription insertNewObjectForEntityForName:@"FavoriteThing" inManagedObjectContext:[self managedObjectContext]];
 
  [favoriteThing setValue:@"WWDC Ticket" forKey:@"thingName"];
  [favoriteThing setValue:@"It sold out in eight days this year, you know?" forKey:@"thingDescription"];
  [favoriteThing setValue:[NSNumber numberWithInt:4] forKey:@"displayOrder"];
 
  [managedObjectContext save:nil];
}

Our Core Data database will now be populated with some initial data so we’ll have something to see. Here is what the initial screen looks like:

Display Order Attribute

In order to implement re-ordering, your entity in your Core Data model will need a displayOrder attribute (you can call it whatever you want, but I’ve named mine displayOrder). This is an integer that will keep track of your indexes and is the field you will use to sort your results in the fetch request sort descriptor. Here is what the code looks like to fetch the entities using the displayOrder attribute as the sort descriptor:

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

- (NSFetchedResultsController *)fetchedResultsController
{
  if (fetchedResultsController) return fetchedResultsController;
 
  NSFetchRequest *fetchRequest = [[NSFetchRequest alloc] init];
  NSEntityDescription *entity = 
               [NSEntityDescription entityForName:@"FavoriteThing" 
                           inManagedObjectContext:managedObjectContext];
 
  [fetchRequest setEntity:entity];
 
  NSSortDescriptor *sortDescriptor = 
              [[NSSortDescriptor alloc] initWithKey:@"displayOrder" 
                                          ascending:YES];
 
  NSArray *sortDescriptors = [[NSArray alloc] 
                              initWithObjects:sortDescriptor, nil];  
  [fetchRequest setSortDescriptors:sortDescriptors];
 
  NSFetchedResultsController *aFetchedResultsController = 
              [[NSFetchedResultsController alloc] initWithFetchRequest:fetchRequest 
                                                  managedObjectContext:managedObjectContext
                                                    sectionNameKeyPath:nil cacheName:@"ThingsCache"];
  aFetchedResultsController.delegate = self;
  [self setFetchedResultsController:aFetchedResultsController];
 
  [aFetchedResultsController release];
  [fetchRequest release];
  [sortDescriptor release];
  [sortDescriptors release];
 
  return fetchedResultsController;
}

Your Core Data entity that you want to re-order should look something like this in the data model editor in Xcode:

Favorites Change

This post is about re-ordering so here is the point. NSFetchedResultsController doesn’t have a built in way to re-order the results, so load them into an NSMutableArray, rearrange them there, and then re-iterate over the items once sorted setting each of their displayOrder field as you go. Then save the managed object context and you’re all re-ordered.

The reason we use an NSMutableArray is because we can insert and remove managed object pointers to/from the array without triggering any changes to the data store. When you make changes to the objects themselves the change is reflected immediately–which is often what we want, but sometimes we don’t as in this case. In Marcus’ Core Data book he points out that you can keep KVO messages from being sent when you want to change a managed object’s attributes by calling -setPrimitiveValue:forKey, but it seemed simpler to me to just re-arrange the objects in an array, and then make the change to each of the object’s displayOrder attribute. Here is the code you use to re-order the results:

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

- (void)tableView:(UITableView *)tableView 
moveRowAtIndexPath:(NSIndexPath *)sourceIndexPath 
      toIndexPath:(NSIndexPath *)destinationIndexPath;
{  
  NSMutableArray *things = [[fetchedResultsController fetchedObjects] mutableCopy];
 
  // Grab the item we're moving.
  NSManagedObject *thing = [[self fetchedResultsController] objectAtIndexPath:sourceIndexPath];
 
  // Remove the object we're moving from the array.
  [things removeObject:thing];
  // Now re-insert it at the destination.
  [things insertObject:thing atIndex:[destinationIndexPath row]];
 
  // All of the objects are now in their correct order. Update each
  // object's displayOrder field by iterating through the array.
  int i = 0;
  for (NSManagedObject *mo in things)
  {
    [mo setValue:[NSNumber numberWithInt:i++] forKey:@"displayOrder"];
  }
 
  [things release], things = nil;
 
  [managedObjectContext save:nil];
}

Further Considerations

You may be thinking that if you iterate through every object in your results you’re actually loading them into memory. This is true, but not something to be concerned about for a couple reasons. First, the results were loaded into memory to display in the table view already. Also, in any table view where you are planning to re-order your results, it is highly unlikely that your list of objects will be very long as trying to re-order too many objects would just prove frustrating for your user and your design has just clearly demonstrated the need to be re-designed at that point anyhow.

Finishing Up

There are just a few more points I want to make before we’re done.

The project template I used is just the default navigation template along with Core Data for storage.

In order for the table view to display the detail text, you need to instantiate your UITableViewCells using the UITableViewCellStyleSubtitle constant. Here is the code to do so:

1
2
3
4
5
6
7
8

static NSString *CellIdentifier = @"Cell";
 
UITableViewCell *cell = [tableView dequeueReusableCellWithIdentifier:CellIdentifier];
if (cell == nil)
{
  cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitle 
                                 reuseIdentifier:@"Cell"] autorelease];
}

Finally, remember that you have to implement -canMoveRowAtIndexPath and return YES if you want the re-order control to display:

1
2
3
4

- (BOOL)tableView:(UITableView *)tableView canMoveRowAtIndexPath:(NSIndexPath *)indexPath
{
  return YES;
}

Conclusion

The NSFetchedResulsController in tandem with a simple NSMutableArray works great to provide re-ordering for your table views. Until next time.

Download the source code for the Favorite Things project.

A situation that I believe we are going to be seeing more and more often is one where application developers are writing multiple “versions” of their applications to be used on the desktop, their iPhone and now the iPad.

Because of that situation, it is becoming even more important that we write as much portable code as possible. Fortunately, our model can be completely portable between the two platforms.

NSImage vs UIImage

The primary issue with creating a portable model and model objects is images. Now, if the images are stored on disk and only referenced in your Core Data model, then you don’t have an issue. Since you are storing the images on disk in a portable format (png, jpeg, etc.) then they will port right over to all of the platforms you are targeting.

But what happens when you are working with small images that should be stored within Core Data? Simple right, just use a transformable data type and stick the image right in there.

Unfortunately that fails in the portability department.

The issue is that on the desktop you are storing a serialized version of the NSImage instance and on the other devices you are storing an instance of UIImage. Two different data structures that are incompatible. So what is the right answer?

Store the images in a portable format even in Core Data.

But that is hard right?

Fortunately if we create concrete subclasses of any entity that needs to store images it is a small amount of code and some conditional compiling.

MyEntityWithAnImage.h

1
2
3
4
5
6
7
8
9
10
11
12

 
@interface MyEntityWithAnImage : NSManagedObject
{
}
 
#ifdef IPHONEOS_DEPLOYMENT_TARGET
@property (nonatomic, retain) UIImage *image;
#else
@property (nonatomic, retain) NSImage *image;
#endif
 
@end

In the header we declare the same property and the use some conditional compiling to determine which definition should be used. On the desktop the property image will return an NSImage and on the other platforms it will return a UIImage. But how do we work this magic?

MyEntityWithAnImage.m

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

#ifdef IPHONEOS_DEPLOYMENT_TARGET
 
- (void)setImage:(UIImage*)image
{
  [self willChangeValueForKey:@"image"];
 
  NSData *data = UIImagePNGRepresentation(image);
  [myManagedObject setImage:data];
  [self setPrimitiveValue:data forKey:@"image"];
  [self didChangeValueForKey:@"image"];
}
 
- (UIImage*)image
{
  [self willAccessValueForKey:@"image"];
  UIImage *image = [UIImage imageWithData:[self primitiveValueForKey:@"image"];
  [self didAccessValueForKey:@"image"];
  return image;
}
 
#else
 
- (void)setImage:(NSImage*)image
{
  [self willChangeValueForKey:@"image"];
  NSBitmapImageRep *bits = [[image representations] objectAtIndex: 0];
 
  NSData *data = [bits representationUsingType:NSPNGFileType properties:nil];
  [myManagedObject setImage:data];
  [self setPrimitiveValue:data forKey:@"image"];
  [self didChangeValueForKey:@"image"];
}
 
- (NSImage*)image
{
  [self willAccessValueForKey:@"image"];
  NSImage *image = [[NSImage alloc] initWithData:[self primitiveValueForKey:@"image"]];
  [self didAccessValueForKey:@"image"];
  return [image autorelease];
}
 
#endif
 
@end

Here we are overriding the dynamic accessors and implementing our own. We are fully KVO compliant and notify when we are accessing or changing the image value.

In the desktop version we grab the bitmap image representation and then get the PNG representation of it and store that representation into Core Data as NSData.

In the Cocoa Touch version we are using the C function which returns the PNG representation of the UIImage instance directly. We are again storing that as NSData into our image property.

In both cases the getter reverses the process by loading the NSData back into the appropriate image instance.

Wrap Up

This makes the code external to our NSManagedObject completely unaware of the actual data storage and they just know that they are getting back the object they need to work with.

BTW, if anyone knows of another pre-processor variable that I should be using for this instead of IPHONEOS_DEPLOYMENT_TARGET please let me know. I am not 100% confident that IPHONEOS_DEPLOYMENT_TARGET is the best variable to be testing against.

Do you like this idea, hate it? Tell me in person at NSConferenceUSA! Tickets are still available and it will be great to see you there.

If that is too soon then please catch me at 360 iDev in April!

Specifically this article walks through using the NSFetchedResultsController and some best practices in its use. The magazine is available for free on their website, The Pragmatic Bookshelf.

Add the following to iTunesFilter_AppDelegate.h:

IBOutlet NSSearchField *searchField;
IBOutlet NSArrayController *songArrayController;

and

- (IBAction)filterSongs:(id)sender;

With those changes I can go into Interface Builder and wire up the NSSearchField to searchField and my NSArrayController to songArrayController. I also make the action of the NSSearchField, filterSongs:.

I have one more change and that is to make the Action of the NSSearchField “Sent on End Editing”

All we need now is to add the code for -filterSongs to iTunesFilter_AppDelegate.m:

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

- (IBAction)filterSongs:(id)sender {
NSMutableString *searchText = [NSMutableString stringWithString:[searchField stringValue]];
 
// Remove extraenous whitespace
while ([searchText rangeOfString:@"Â  "].location != NSNotFound) {
    [searchText replaceOccurrencesOfString:@"Â  " withString:@" " options:0 range:NSMakeRange(0, [searchText length])];
}
 
//Remove leading space
if ([searchText length] != 0) [searchText replaceOccurrencesOfString:@" " withString:@"" options:0 range:NSMakeRange(0,1)];
 
//Remove trailing space
if ([searchText length] != 0) [searchText replaceOccurrencesOfString:@" " withString:@"" options:0 range:NSMakeRange([searchText length]-1, 1)];
 
if ([searchText length] == 0) {
    [songArrayController setFilterPredicate:nil];
    return;
}
 
NSArray *searchTerms = [searchText componentsSeparatedByString:@" "];
 
if ([searchTerms count] == 1) {
    NSPredicate *p = [NSPredicate predicateWithFormat:@"(name contains[cd] %@) OR (album contains[cd] %@) OR (artist contains[cd] %@)", searchText, searchText, searchText];
    [songArrayController setFilterPredicate:p];
} else {
    NSMutableArray *subPredicates = [[NSMutableArray alloc] init];
    for (NSString *term in searchTerms) {
        NSPredicate *p = [NSPredicate predicateWithFormat:@"(name contains[cd] %@) OR (album contains[cd] %@) OR (artist contains[cd] %@)", term, term, term];
        [subPredicates addObject:p];
    }
    NSPredicate *cp = [NSCompoundPredicate andPredicateWithSubpredicates:subPredicates];
 
    [songArrayController setFilterPredicate:cp];
}
}

Here’s how it works: After we remove extra whitespace in the string, we breakdown the string into each word (-componentsSeparatedByString:). Then we build an NSPredicate for each word in the string, before the real magic happens by combining these together using NSCompoundPredicate andPredicateWithSubpredicates:

In the end I get a predicate that looks like this: ((name contains[cd] yesterday) or (artist contains[cd] yesterday) or (album contains[cd] yesterday)) and ((name contains[cd] beatles) or (artist contains[cd] beatles) or (album contains[cd] beatles))

iTunesFilter Sample Application

While new Cocoa programmers will find it a great help to getting started quickly with Core Data, the book also covers some really interesting and advanced topics such as data versioning and migration, Spotlight/Quick Look integration, Sync Services, and multi-threading. You can really see Marcus’ command of the subject shine in these chapters which are already available in the beta.

Give Marcus some feedback on the book as it progresses. It’s going to be a great reference for any Cocoa Developer looking to harness the power of Core Data.

$21.00 for the beta PDF $41.35 for the beta PDF plus hard copy when it’s released in March.

Mad props to Marcus. Congratulations!

The Conflict With NSUndoManager

For those familiar with the inner workings of Cocoa’s undo support (and if you are not familiar with it, check out the April edition of MacTech ;-) , all of the undo events are registered with an NSUndoManager. In a normal document model application, the window controller (or the window’s delegate if set to something other than the controller) will supply an NSUndoManager for all of the text fields and other editable bits in the window.

This works fine until Core Data comes along. The reason for this is that the NSManagedObjectContext has its own NSUndoManager that is registering those same events and can easily get out of sync.

What I prefer to do is avoid the double NSUndoManager and just use the one included with the NSManagedObjectContext. This can be done by implementing one of the window delegate methods:

1
2
3
4
5
6
7
8
9

- (NSUndoManager *)windowWillReturnUndoManager:(NSWindow *)window
{
  return [self undoManager];
}
 
- (NSUndoManager*)undoManager
{
  return [[self managedObjectContext] undoManager];
}

By utilizing the NSUndoManager that is included in the context, some very powerful features are enabled.

Grouping sheet modifications

A common UI design is to allow the editing of an object in a sheet. The user double clicks on the item or otherwise indicates that they want to edit it and a sheet drops down allowing them to change the values. Naturally, that sheet has an NSUndoManager attached to it (can even use the one from Core Data) and each individual field can be undone. However, how to do we handle the cancel button or the ability to undo the entire sheet?

Both of the above can be handled with groupings inside of the NSManagedObjectContext object’s NSUndoManager. The methods would work as follows:

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

- (void)presentEditSheet:(id)sender
{
  [[self undoManager] beginUndoGrouping];
  [NSApp beginSheet:[self editSheet] 
     modalForWindow:[self window] 
      modalDelegate:nil 
     didEndSelector:NULL 
        contextInfo:nil];
}
 
- (void)acceptChanges:(id)sender
{
  [[self editSheet] orderOut:sender];
  [NSApp endSheet:[self editSheet]];
  [[self undoManager] endUndoGrouping];
  [[self undoManager] setActionName:@"Object edit"];
}
 
- (void)cancelChanges:(id)sender
{
  [[self editSheet] orderOut:sender];
  [NSApp endSheet:[self editSheet]];
  [[self undoManager] endUndoGrouping];
  [[self undoManager] undo];
}

In this example I have started an undo group before presenting the sheet. After the sheet is closed I then end the grouping and if the sheet was not cancelled I give the group a name. This name will display in the menu and allow all of the changes inside of the sheet to be undone in one stroke. If the sheet is cancelled then the group is still closed but I immediately call undo instead and everything that occurred within the sheet is wiped clean.

Conclusion

By only using one NSUndoManager it makes life a lot simplier and gives consistent results to the user. This technique can also be used in a document model application but each document will have to reference the appropriate NSUndoManager that is associated with its own NSManagedObjectContext.

Feedback

If you have some other interesting ways to use the NSUndoManager I would love to hear about them either here in the comments or you can email me directly at marcus at cimgf.com.