Entities

An entity can be thought as the Core Data analogue to an Objective-C class declaration. In fact, when using an entity in your application, you essentially treat it like an Objective-C class with some Core Data-specific implementation. You use the model editor to define the properties that define your entity. Each entity is given a name (in this case, Event), which must begin with a capital letter. When you ran CoreDataApp earlier, every time you pressed the Add (+) button, a new instance of Event was instantiated and stored in the application’s persistent store.

Make sure the Utility pane is exposed, and select the Event entity. Now look at the inspector in the Utility pane (make sure the enspector is showing by selecting the Inspector button in the Inspector selector bar). Note that the Inspector pane now allows you to edit or change aspects of the entity (Figure 2-10). We’ll get to the details of the inspector later.

Fetch Requests

While a fetched property is like a query that originates with a single managed object, a fetch request is more like a class method that implements a canned query. For example, you might build a fetch request named canChangeLightBulb that returns a list of Employees who are taller than 80 inches (about 2 meters). You can run the fetch request any time you need a light bulb changed. When you run it, Core Data searches the persistent store to find the current list of potential light-bulb-changing Employees.

You will create many fetch requests programmatically in the next few chapters, and you’ll be looking at a simple one a little later in this chapter in the “Creating a Fetched Results Controller” section.

Configurations

A configuration is a set of entities. Different configurations may contain the same entity. Configurations are use to define which entities are stored in which persistent store. Most of the time, you won’t need anything other than the default configuration. We won’t cover using multiple configurations in this book. If you want to learn more, check the Apple Developer site or Pro Core Data for iOS, 2^nd Edition (www.apress.com/9781430236566).

The Data Model Class: NSManagedObjectModel

Although you won’t typically access your application’s data model directly, you should be aware of the fact that there is an Objective-C class that represents the data model in memory. This class is called NSManagedObjectModel, and the template automatically creates an instance of NSManagedObjectModel based on the data model file in your project. Let’s take a look at the code that creates it now.

In the Navigation pane, open the CoreDataApp group and AppDelegate.m. In the Editor jump bar, click the last menu (it should read No Selection) to bring up a list of the methods in this class (see Figure 2-13). Select -managedObjectModel in the Core Data Stack section, which will take you to the method that creates the object model based on the CoreDataApp.xcdatamodel file.

The method should look like this:

// Returns the managed object model for the application.
// If the model doesn't already exist, it is created from the application's model.
- (NSManagedObjectModel *)managedObjectModel
{
    if (_managedObjectModel != nil) {
        return _managedObjectModel;
    }
    NSURL *modelURL = [[NSBundle mainBundle] URLForResource:@"CoreDataApp"
                                              withExtension:@"momd"];
    _managedObjectModel = [[NSManagedObjectModel alloc] initWithContentsOfURL:modelURL];
    return _managedObjectModel;
}

The first checks the instance variable _managedObjectModel to see if it’s nil. This accessor method uses a form of lazy loading. The underlying instance variable doesn’t actually get instantiated until the first time the accessor method is called. For this reason, you should never, ever access _managedObjectModel directly (except within the accessor method itself, of course). Always make sure to use the accessor methods. Otherwise, you could end up trying to make calls on an object that hasn’t been created yet.

If _managedObjectModel is nil, you can go get your data model. By default XCode should have written the following two lines of code to accomplish this for you:

NSURL *modelURL = [[NSBundle mainBundle] URLForResource:@"CoreDataApp"
                                          withExtension:@"momd"];
_managedObjectModel = [[NSManagedObjectModel alloc] initWithContentsOfURL:modelURL];

Remember how we said that a persistent store was associated with a single data model? Well, that’s true, but it doesn’t tell the whole story. You can combine multiple .xcdatamodel files into a single instance of NSManagedObjectModel, creating a single data model that combines all the entities from multiple files. If you are planning on having more than one model, you can change those two lines of code to one.

This one line of code will take any .xcdatamodel files that might be in your Xcode project and combines them together into a single instance of NSManagedObjectModel:

_managedObjectModel = [NSManagedObjectModel mergedModelFromBundles:nil];

So, for example, if you create a second data model file and add it to your project, that new file will be combined with CoreDataApp.xcdatamodel into a single managed object model that containes the contents of both files. This allows you to split up your application’s data model into multiple smaller and more manageable files.

The vast majority of iOS applications that use Core Data have a single persistent store and a single data model, so the default template code will work beautifully most of the time. That said, Core Data does support the use of multiple persistent stores. You could, for example, design your application to store some of its data in a SQLite persistent store and some of it in a binary flat file. If you find that you need to use multiple data models, remember to change the template code here to load the managed object models individually using mergedModelFromBundles:.

The Persistent Store and Persistent Store Coordinator

The persistent store, which is sometimes referred to as a backing store, is where Core Data stores its data. By default, on iOS devices Core Data uses a SQLite database contained in your application’s Documents folder as its persistent store. But this can be changed without impacting any of the other code you write by tweaking a single line of code. We’ll show you the actual line of code to change in a few moments.

Every persistent store is associated with a single data model, which defines the types of data that the persistent store can store.

The persistent store isn’t actually represented by an Objective-C class. Instead, a class called NSPersistentStoreCoordinator controls access to the persistent store. In essence, it takes all the calls coming from different classes that trigger reads or writes to the persistent store and serializes them so that multiple calls against the same file are not being made at the same time, which could result in problems due to file or database locking.

As is the case with the managed object model, the template provides you with a method in the application delegate that creates and returns an instance of a persistent store coordinator. Other than creating the store and associating it with a data model and a location on disk (which is done for you in the template), you will rarely need to interact with the persistent store coordinator directly. You’ll use high-level Core Data calls, and Core Data will interact with the persistent store coordinator to retrieve or save the data.

Let’s take a look at the method that returns the persistent store coordinator. In CoreDataAppDelegate.m, select -persistentStoreCoordinator from the function pop-up menu. Here’s the method:

// Returns the persistent store coordinator for the application.
// If the coordinator doesn't already exist, it is created and the application's store added to it.
- (NSPersistentStoreCoordinator *)persistentStoreCoordinator
{
    if (_persistentStoreCoordinator != nil) {
        return _persistentStoreCoordinator;
    }
    NSURL *storeURL = [[self applicationDocumentsDirectory]
          URLByAppendingPathComponent:@"CoreDataApp.sqlite"];
    NSError *error = nil;
    _persistentStoreCoordinator = [[NSPersistentStoreCoordinator alloc]
                                          initWithManagedObjectModel:[self managedObjectModel]];
    if (![_persistentStoreCoordinator addPersistentStoreWithType:NSSQLiteStoreType
  	                           configuration:nil
  	                                     URL:storeURL
  	                                 options:nil
  	                                   error:&error]) {
        /*
         Replace this implementation with code to handle the error appropriately.
         abort() causes the application to generate a crash log and terminate. You should not use
         this function in a shipping application, although it may be useful during development.
         Typical reasons for an error here include:
         * The persistent store is not accessible;
         * The schema for the persistent store is incompatible with current managed object model.
         Check the error message to determine what the actual problem was.
         If the persistent store is not accessible, there is typically something wrong with the file
         path. Often, a file URL is pointing into the application's resources directory instead of a
         writeable directory.
         If you encounter schema incompatibility errors during development, you can reduce their
             frequency by:
         * Simply deleting the existing store:
         [[NSFileManager defaultManager] removeItemAtURL:storeURL error:nil]
         * Performing automatic lightweight migration by passing the following dictionary as the
             options parameter:
         @{NSMigratePersistentStoresAutomaticallyOption:@YES,
                    NSInferMappingModelAutomaticallyOption:@YES}
         Lightweight migration will only work for a limited set of schema changes; consult "Core Data
         Model Versioning and Data Migration Programming Guide" for details.
         */
        NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
        abort();
    }
    return _persistentStoreCoordinator;
}

As with the managed object model, this persistentStoreCoordinator accessor method uses lazy loading and doesn’t instantiate the persistent store coordinator until the first time it is accessed. Then it creates a path to a file called CoreDataApp.sqlite in the Documents directory in your application’s sandbox. The template will always create a filename based on your project’s name. If you want to use a different name, you can change it here, though it generally doesn’t matter what you call the file since the user will never see it.

Take a look at this line of code:

if (![_persistentStoreCoordinator addPersistentStoreWithType:NSSQLiteStoreType
                                 configuration:nil
                                 URL:storeURL
                                 options:nil
                                 error:&error]) {

The first parameter to this method, NSSQLiteStoreType, determines the type of the persistent store. NSSQLiteStoreType is a constant that tells Core Data to use a SQLite database for its persistent store. If you want your application to use a single, binary flat file instead of a SQLite database, you could specify the constant NSBinaryStoreType instead of NSSQLiteStoreType. The vast majority of the time, the default setting is the best choice, so unless you have a compelling reason to change it, leave it alone.

Reviewing the Data Model

Before you move on to other parts of Core Data, let’s quickly review how the pieces you’ve looked at so far fit together. You might want to refer back to Figure 2-7.

The persistent store (or backing store) is a file on an iOS device’s file system that can be either a SQLite database or a binary flat file. A data model file, contained in one or more files with an extension of .xcdatamodel, describes the structure of your application’s data. This file can be edited in Xcode. The data model tells the persistent store coordinator the format of all data stored in that persistent store. The persistent store coordinator is used by other Core Data classes that need to save, retrieve, or search for data. Easy enough, right? Let’s move on.

Saves On Terminate

While you’re in the application delegate, scroll up to another method called applicationWillTerminate:, which saves changes to the context if any have been made. The changes are saved to the persistent store. As its name implies, this method is called just before the application exits.

- (void)applicationWillTerminate:(UIApplication *)application
{
    // Saves changes in the application's managed object context before the application
    // terminates.
    [self saveContext];
}

This is a nice bit of functionality, but there may be times when you don’t want the data to be saved. For example, what if the user quits after creating a new entity, but before entering any data for that entity? In that case, do you really want to save that empty managed object into the persistent store? Possibly not. You’ll look at dealing with situations like that in the next few chapters.

Load Data From the Persistent Store

Run the Core Data application you built earlier and press the plus button a few times (see Figure 2-6). Quit the simulator, and then run the application again. Note that the timestamps from your previous runs were saved into the persistent store and loaded back in for this run.

Click MasterViewController.m so you can see how this happens. As you can probably guess from the filename, MasterViewController is the view controller class that acts as your application’s, well, master view controller. This is the view controller for the view you can see in Figure 2-6.

Once you’ve clicked the filename, you can use the Editor jump bar’s Function menu to find the viewDidLoad: method, although it will probably be on your screen already since it’s the first method in the class. The default implementation of the method looks like this:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
    self.navigationItem.leftBarButtonItem = self.editButtonItem;
    UIBarButtonItem *addButton =     [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemAdd                                                     target:self                                                     action:@selector(insertNewObject:)];
    self.navigationItem.rightBarButtonItem = addButton;
}

The first thing the method does is call super. Next, it sets up the Edit and Add buttons. Note that MasterViewController inherits from UITableViewController, which in turn inherits from UIViewController. UIViewController provides a property named editButtonItem, which returns an Edit button. Using dot notation, you retrieve editButtonItem and pass it to the leftBarButtonItem property of the navigationItem property. Now the Edit button is the left button in the navigation bar.

Now let’s focus on the Add button. Since UIViewController does not provide an Add button, use alloc to create one from scratch and the add it as the right button in the navigation bar. The code is fairly straightforward:

UIBarButtonItem *addButton =     [[UIBarButtonItem alloc] initWithBarButtonSystemItem:UIBarButtonSystemItemAdd
                                                  target:self
                                                  action:@selector(insertNewObject:)];
self.navigationItem.rightBarButtonItem = addButton;

So, with the basic user interface set up, it’s time to look at how the fetched results controller works.

The Fetched Results Controller

Conceptually speaking, the fetched results controller isn’t quite like the other generic controllers you’ve seen in the iOS SDK. If you’ve used Cocoa bindings and the generic controller classes available on the Mac, such as NSArrayController, then you’re already familiar with the basic idea. If you’re not familiar with those generic controller classes, a little explanation is probably in order.

Most of the generic controller classes in the iOS SDK (such as UINavigationController, UITableViewController, and UIViewController) are designed to act as the controller for a specific type of view. View controllers, however, are not the only types of controller classes that Cocoa Touch provides, although they are the most common. NSFetchedResultsController is an example of a controller class that is not a view controller.

NSFetchedResultsController is designed to handle one very specific job, which is to manage the objects returned from a Core Data fetch request. NSFetchedResultsController makes displaying data from Core Data easier than it would otherwise be because it handles a bunch of tasks for you. It will, for example, purge any unneeded objects from memory when it receives a low-memory warning and reload them when it needs them again. If you specify a delegate for the fetched results controller, your delegate will be notified when certain changes are made to its underlying data.

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView
{
    return [[self.fetchedResultsController sections] count];
}

- (NSInteger)tableView:(UITableView *)tableView numberOfRowsInSection:(NSInteger)section
{
    id <NSFetchedResultsSectionInfo> sectionInfo =         [self.fetchedResultsController sections] objectAtIndex:section];
    return [sectionInfo numberOfObjects];
}

- (NSFetchedResultsController *)fetchedResultsController
{
    if (_fetchedResultsController != nil) {
        return _fetchedResultsController;
    }
    NSFetchRequest *fetchRequest = [[NSFetchRequest alloc] init];
    // Edit the entity name as appropriate.
    NSEntityDescription *entity = [NSEntityDescription entityForName:@"Event"
                        inManagedObjectContext:self.managedObjectContext];
    [fetchRequest setEntity:entity];
    // Set the batch size to a suitable number.
    [fetchRequest setFetchBatchSize:20];
    // Edit the sort key as appropriate.
    NSSortDescriptor *sortDescriptor = [[NSSortDescriptor alloc] initWithKey:@"timeStamp"
                                                                ascending:NO];
    NSArray *sortDescriptors = @[sortDescriptor];
    [fetchRequest setSortDescriptors:sortDescriptors];
    // Edit the section name key path and cache name if appropriate.
    // nil for section name key path means "no sections".
    NSFetchedResultsController *aFetchedResultsController = [[NSFetchedResultsController alloc]
                   initWithFetchRequest:fetchRequest
                   managedObjectContext:self.managedObjectContext
                   sectionNameKeyPath:nil cacheName:@"Master"];
    aFetchedResultsController.delegate = self;
    self.fetchedResultsController = aFetchedResultsController;
 NSError *error = nil;
 if (![self.fetchedResultsController performFetch:&error]) {
      // Replace this implementation with code to handle the error appropriately.
      // abort() causes the application to generate a crash log and terminate. You should
             // not use this function in a shipping application, although it may be useful during
             // development.
     NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
     abort();
 }
    return _fetchedResultsController;
}

NSFetchRequest *fetchRequest = [[NSFetchRequest alloc] init];
// Edit the entity name as appropriate.
NSEntityDescription *entity = [NSEntityDescription entityForName:@"Event"                                          inManagedObjectContext:self.managedObjectContext];
[fetchRequest setEntity:entity];

// Set the batch size to a suitable number.
[fetchRequest setFetchBatchSize:20];

// Edit the sort key as appropriate.
NSSortDescriptor *sortDescriptor = [[NSSortDescriptor alloc] initWithKey:@"timeStamp" ascending:NO];

NSArray *sortDescriptors = @[sortDescriptor];
[fetchRequest setSortDescriptors:sortDescriptors];

// Edit the section name key path and cache name if appropriate.
// nil for section name key path means "no sections".
NSFetchedResultsController *aFetchedResultsController =     [[NSFetchedResultsController alloc] initWithFetchRequest:fetchRequest                                         managedObjectContext:self.managedObjectContext                                           sectionNameKeyPath:nil                                                    cacheName:@"Master"];

aFetchedResultsController.delegate = self;
self.fetchedResultsController = aFetchedResultsController;

NSError *error = nil;
if (![self.fetchedResultsController performFetch:&error]) {
    // Replace this implementation with code to handle the error appropriately.
    // abort() causes the application to generate a crash log and terminate. You should not use this
    // function in a shipping application, although it may be useful during development.
    NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
    abort();
}
return _fetchedResultsController;

- (void)controllerWillChangeContent:(NSFetchedResultsController *)controller
{
    [self.tableView beginUpdates];
}

- (void)controllerDidChangeContent:(NSFetchedResultsController *)controller
{
    [self.tableView endUpdates];
}

- (void)controller:(NSFetchedResultsController *)controller didChangeObject:(id)anObject
       atIndexPath:(NSIndexPath *)indexPath forChangeType:(NSFetchedResultsChangeType)type
      newIndexPath:(NSIndexPath *)newIndexPath
{
    UITableView *tableView = self.tableView;
    switch(type) {
        case NSFetchedResultsChangeInsert:
            [tableView insertRowsAtIndexPaths:@[newIndexPath]
             withRowAnimation:UITableViewRowAnimationFade];
            break;
        case NSFetchedResultsChangeDelete:
            [tableView deleteRowsAtIndexPaths:@[indexPath]
             withRowAnimation:UITableViewRowAnimationFade];
            break;
        case NSFetchedResultsChangeUpdate:
            [self configureCell:[tableView cellForRowAtIndexPath:indexPath] atIndexPath:indexPath];
            break;
        case NSFetchedResultsChangeMove:
            [tableView deleteRowsAtIndexPaths:@[indexPath]
             withRowAnimation:UITableViewRowAnimationFade];
            [tableView insertRowsAtIndexPaths:@[newIndexPath]
             withRowAnimation:UITableViewRowAnimationFade];
            break;
    }
}

- (void)controller:(NSFetchedResultsController *)controller
 didChangeSection:(id <NSFetchedResultsSectionInfo>)sectionInfo
 atIndex:(NSUInteger)sectionIndex
 forChangeType:(NSFetchedResultsChangeType)type
{
    switch(type) {
        case NSFetchedResultsChangeInsert:
            [self.tableView insertSections:[NSIndexSet indexSetWithIndex:sectionIndex]
      withRowAnimation:UITableViewRowAnimationFade];
            break;
        case NSFetchedResultsChangeDelete:
            [self.tableView deleteSections:[NSIndexSet indexSetWithIndex:sectionIndex]
       withRowAnimation:UITableViewRowAnimationFade];
            break;
    }
}

NSManagedObject *object = [[self fetchedResultsController] objectAtIndexPath:indexPath];

Creating and Inserting a New Managed Object

From the function menu in the editor pane, select insertNewObject, which is the method that is called when the + button is pressed in the sample application. It’s a nice, simple example of how to create a new managed object, insert it into a managed object context, and then save it to the persistent store.

- (void)insertNewObject:(id)sender
{
    NSManagedObjectContext *context = [self.fetchedResultsController managedObjectContext];
    NSEntityDescription *entity = [[self.fetchedResultsController fetchRequest] entity];
    NSManagedObject *newManagedObject =         [NSEntityDescription insertNewObjectForEntityForName:[entity name]                                       inManagedObjectContext:context];
    // If appropriate, configure the new managed object.
    // Normally you should use accessor methods, but using KVC here avoids the need to add a custom class to the template.
    [newManagedObject setValue:[NSDate date] forKey:@"timeStamp"];
    // Save the context.
    NSError *error = nil;
    if (![context save:&error]) {
         // Replace this implementation with code to handle the error appropriately.
         // abort() causes the application to generate a crash log and terminate.         // You should not use this function in a shipping application,          // although it may be useful during development.
        NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
        abort();
    }
}

Notice that the first thing the code does is to retrieve a managed object context from the fetched results controller. In this simple example where there’s only one context, you could also have retrieved the same context from the application delegate. There are a few reasons why the default code uses the context from the fetched results controller. First of all, you already have a method that returns the fetched results controller, so you can get to the context in just one line of code.

NSManagedObjectContext *context = [self.fetchedResultsController managedObjectContext];

More importantly, though, a fetched results controller always knows which context its managed objects are contained by, so even if you decide to create an application with multiple contexts, you’ll be sure that you’re using the correct context if you pull it from the fetched results controller.

Just as you did when you created a fetch request, when inserting a new object, you need to create an entity description to tell Core Data which kind of entity you want to create an instance of. The fetched results controller also knows what entity the objects it manages are, so you can just ask it for that information.

NSEntityDescription *entity = [[self.fetchedResultsController fetchRequest] entity];

Then it’s simply a matter of using a class method on NSEntityDescription to create the new object and insert it into a context.

NSManagedObject *newManagedObject =     [NSEntityDescription insertNewObjectForEntityForName:[entity name]                                   inManagedObjectContext:context];

It does seem a little odd that you use a class method on NSEntityDescription, rather than an instance method on the context you want to insert the new object into, but that’s the way it’s done.

Though this managed object has now been inserted into the context, it still exists in the persistent store. In order to insert it from the persistent store, you must save the context, which is what happens next in this method:

// Save the context.
NSError *error = nil;
if (![context save:&error]) {
    // Replace this implementation with code to handle the error appropriately.
    // abort() causes the application to generate a crash log and terminate.     // You should not use this function in a shipping application,     // although it may be useful during development.
    NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
    abort();
}

As the comment says, you need to handle the error more appropriately than calling abort. We’ll cover this more in the ensuing chapters. Also, notice that you don’t call reloadData on your table view. The fetched results controller will realize that you’ve inserted a new object that meets its criteria and will call the delegate method, which will automatically reload the table.

Deleteing Managed Objects

Deleting managed objects is pretty easy when using a fetched results controller. Use the function menu to navigate to the method called tableView:commitEditingStyle:forRowAtIndexPath:. That method should look like this:

- (void)tableView:(UITableView *)tableView         commitEditingStyle:(UITableViewCellEditingStyle)editingStyle         forRowAtIndexPath:(NSIndexPath *)indexPath
{
    if (editingStyle == UITableViewCellEditingStyleDelete) {
        NSManagedObjectContext *context = [self.fetchedResultsController managedObjectContext];
        [context deleteObject:[self.fetchedResultsController objectAtIndexPath:indexPath]];
        NSError *error = nil;
        if (![context save:&error]) {
             // Replace this implementation with code to handle the error appropriately.
             // abort() causes the application to generate a crash log and terminate.              // You should not use this function in a shipping application,              // although it may be useful during development.
            NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
            abort();
        }
    }
}

The method first makes sure that you’re in a delete transaction (remember that this same method is used for deletes and inserts).

if (editingStyle == UITableViewCellEditingStyleDelete) {

Next, you retrieve the context.

NSManagedObjectContext *context = [self.fetchedResultsController managedObjectContext];

Then the context is asked to delete that object.

[context deleteObject:[self.fetchedResultsController objectAtIndexPath:indexPath]];

Next, the managed object context’s save: method is called to cause that change to be committed to the persistent store.

NSError *error = nil;
if (![context save:&error]) {
    // Replace this implementation with code to handle the error appropriately.
    // abort() causes the application to generate a crash log and terminate. You should not use this
    // function in a shipping application, although it may be useful during development.
    NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
    abort();
}

No need to admonish you again about the call to abort, as we discussed this previously.

And that’s all there is to deleting managed objects.