The data store is the file or group of files that hold your data. This is the actual file written to the disk when the save message is sent to Core Data. Typically, in a mobile application, only one data store file is used. However, it is possible to use a group of files as the data store.

The data store can be a binary data file, an SQLite database, or an in-memory data file, depending on the parameters used when creating the data store. You will see how to specify the storage type for your data in the example at the end of the chapter.

As the developer, you will never directly access the data store. The Persistent Store Coordinator abstracts away access to the data file. In addition, you do not need to concern yourself with the data store implementation. Simply consider it a file that holds all of your data.

This Persistent Store Coordinator acts as a mediator between the managed object context and the data store. The coordinator takes requests for data from the context and forwards them to the appropriate data store. The coordinator also allows the context to access one or more data stores as if they were one. Finally, the coordinator associates a data store with a Managed Object Model. The Persistent Store Coordinator is an instance of the NSPersistentStoreCoordinator class.

The Managed Object Model represents the data model schema. In code, the Managed Object Model is an instance of the NSManagedObjectModel class.

The model consists of a set of entities that define the data objects in your application. When designing your model, you specify the data entities that your application will deal with. You can specify attributes for these entities and define the relationships between them.

You typically create the model graphically using the Xcode data-modeling tool although it is possible to define the model in code. You can think of the managed object model like the Entity-Relationship diagram that you would create when designing a database.

The data model should define each data object used in your application. The Persistent Store Coordinator uses the model to create Managed Objects according to conventions from the entities defined in the model. The coordinator also maps the entities in the model into the physical data store file that Core Data writes to disk.

You will rarely access the object model through your code. If the need arises, you can use the NSManagedObjectModel class. You access the Managed Objects created from the model entities using the Managed Object Context.

The Managed Object Context, also referred to as the context, provides the main interface that you will use to access your managed data objects. The managed object context is an instance of the NSManagedObjectContext class.

You use the context to hold all of your managed data objects. Your managed data objects are either instances or subclasses of the NSManagedObject class. The name Managed Object makes sense as the Managed Object Context manages all of these objects.

You can think of the context as the sandbox that holds all of your application data. You can add objects to the context, delete them, and modify them in memory. Then, when you are ready, you can tell the context to commit its current state to disk. Behind the scenes, the context uses the Persistent Store Coordinator to write your data out to the data store on disk. The context uses the object model to ensure that your data is in a consistent state with respect to your defined relationships, constraints, and validation rules before committing it to disk.

You make fetch requests against the context to fetch data from the data store back into the context. You fetch data into Managed Objects that you use to manipulate and display your data. Fetch requests are similar to SQL SELECT statements. When creating a fetch request, you can provide a predicate to filter your data such as the SQL WHERE clause. You also provide a sort array that functions like the SQL ORDER BY clause.

While you won't be modifying any of the code in the app delegate, it is instructive to look at the code. The code in the app delegate sets up the Core Data stack. Therefore, as you might imagine, there is code to create a Persistent Store Coordinator, Managed Object Model, and Managed Object Context.

The persistentStoreCoordinator getter method returns the Persistent Store Coordinator for the application. Here is the code:

- (NSPersistentStoreCoordinator *)persistentStoreCoordinator {

    if (persistentStoreCoordinator != nil) {
        return persistentStoreCoordinator;
    }

    NSURL *storeUrl = [NSURL fileURLWithPath:
                       [[self applicationDocumentsDirectory]
                        stringByAppendingPathComponent: @"Tasks.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. If it is not possible to recover
         from the error, display an alert panel that instructs the user to quit
         the application by pressing the Home button.

         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.
         */
        NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
        abort();
    }

    return persistentStoreCoordinator;
}
                                                                       

The code first determines if the Persistent Store Coordinator already exists. If it exists, the method returns it to you.

If the coordinator does not exist, the code must create it. In order to create the coordinator, you need to pass in a URL that points to the data store. The template uses the fileURLWithPath: method on the NSURL class to create the URL. You can see that the store name will be Tasks.sqlite.

Next, the code allocates an NSError object to hold the error data that the Persistent Store Coordinator generates if there is a problem configuring the coordinator.

The next line allocates and initializes the coordinator using the Managed Object Model. You will look at the managedObjectModel getter method in a moment. Remember that you use the Persistent Store Coordinator to mediate between the Managed Object Context, the Managed Object Model, and the data store. Therefore, it makes sense that the coordinator would need to have a reference to the model.

Now that the coordinator knows about the model, the code goes on to tell it about the data store. The next line of code adds the data store to the coordinator. You will notice that the type of the data store is NSSQLiteStoreType. This indicates that the template uses the SQLite backing data store. If you wanted to use the binary store, you would change this enumeration value to NSBinaryStoreType, and if you wanted to use the in-memory store, you would set the value to NSInMemoryStoreType. Remember that most often you will be using the SQLite backing store.

The rest of the code logs an error if there was a problem adding the SQLite store to the coordinator. If there was no error, the method returns the coordinator.

The getter function to return the Managed Object Model is very straightforward:

- (NSManagedObjectModel *)managedObjectModel {

    if (managedObjectModel != nil) {
        return managedObjectModel;
    }
    managedObjectModel = [[NSManagedObjectModel
                           mergedModelFromBundles:nil] retain];
    return managedObjectModel;
}
                                                         

If the model already exists, the getter method returns it. If not, the code creates a new Managed Object Model by merging all of the model files contained in the application bundle. The Tasks.xcdatamodel file in the Resources folder contains the object model. This file is included with the application bundle, so this method takes that file and uses it to create the NSManagedObjectModel object.

The last bit of interesting code in the App Delegate is the managedObjectContext getter method:

- (NSManagedObjectContext *) managedObjectContext {

    if (managedObjectContext != nil) {
        return managedObjectContext;
    }

    NSPersistentStoreCoordinator *coordinator =
        [self persistentStoreCoordinator];
    if (coordinator != nil) {
        managedObjectContext = [[NSManagedObjectContext alloc] init];
        [managedObjectContext setPersistentStoreCoordinator: coordinator];
    }
    return managedObjectContext;
}
                                                         

This method works similarly to the previous two. The first thing it does is check to see if the context already exists. If the context exists, the method returns it.

Next, the code gets a reference to the persistentStoreCoordinator. If you refer back to Figure 5-1, you will see that the Managed Object Context needs only a reference to the Persistent Store Coordinator.

If the code successfully gets a reference to the coordinator, it goes on to create the context. Then, the code sets the coordinator for the context and returns the context.

I hope that the way in which all of the objects in the Core Data stack fit together is becoming a bit clearer. Remember that you did not have to write any code to create the data store, the Persistent Store Coordinator, the Managed Object Model, or the Managed Object Context. The template code takes care of all of this for you automatically. You will see that the only interface that you need to deal with is that of the Managed Object Context.

Before you examine the RootViewController and how to use it to create your TableView using Core Data, let's look at the template Managed Object Model. If you open the Resources folder in Xcode and double-click on Tasks.xcdatamodel, you should see something similar to Figure 5-3.

Figure 5.3. The default Object Model

The code template creates a default entity called "Event." The blue highlighting and resize handles indicate that the Event entity is selected. Click anywhere else in the diagram to de-select the Event entity and it will turn pink to indicate that it is no longer selected. Click on the Event entity again to select it.

There are three panes in the top of the data-modeling tool. From left to right they are the Entities pane, the Properties pane, and the Detail pane. The Entities pane provides a list of all of the entities in your model. The Properties pane lists the properties of the currently selected entity, and the Detail pane shows details related to whatever is currently selected, either an entity or property. The bottom portion of the tool displays a graphical representation of your model called the Diagram View. The next chapter provides more detail on using the data-modeling tool.

You can see in Figure 5-3 that the Event entity has an attribute called timeStamp. If you select the Event entity and then select the timeStamp property in the Properties pane, you will see the details of the timeStamp attribute in the Detail pane. You should see that the timeStamp attribute is optional and that it is a Date type.

Your managed object context will manage the objects defined by the Event entity. Remember that when you created the Persistent Store Coordinator, you initialized it with all of the managed object models in the bundle. Then, when you created the context, it used the Persistent Store Coordinator. Next, you will see how you use the Event entity to create and manage Core Data Managed Objects in code.

The RootViewController is a subclass of UITableViewController and contains the TableView that you will use to display your data. This class has a property that holds the context, which the Application Delegate sets when it creates the RootViewController instance. The RootViewController also has a property that holds an NSFetchedResultsController.

The NSFetchedResultsController class is the glue that binds the results of a fetch request against your datasource to a TableView. You will look at the NSFetchedResultsController class in more detail in Chapter 6.

Figure 5-4 shows a high-level view of how the NSFetchedResultsController class works. The class takes a fetch request and a context as its inputs and calls delegate methods when the data in the fetch request changes. The controller implements methods that you use when implementing the TableView delegate methods that you are familiar with from Chapter 3.

Figure 5.4. NSFetchedResultsController usage

The first thing to notice is that the RootViewController implements the NSFetchedResultsControllerDelegate protocol. You can see this in the RootViewController.h header file. Remember that declaring that you implement a protocol is a contract that commits you to implementing certain methods. Classes that do not implement this protocol cannot be delegates for an NSFetchedResultsController.

The following is the code for the getter method for the fetchedResultsController property:

- (NSFetchedResultsController *)fetchedResultsController {

    if (fetchedResultsController != nil) {
        return fetchedResultsController;
    }

    /*

Set up the fetched results controller.
    */
    // Create the fetch request for the entity.
    NSFetchRequest *fetchRequest = [[NSFetchRequest alloc] init];
    // Edit the entity name as appropriate.
    NSEntityDescription *entity =
        [NSEntityDescription entityForName:@"Event"
                    inManagedObjectContext: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 =
        [[NSArray alloc] initWithObjects:sortDescriptor, nil];

    [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:managedObjectContext
            sectionNameKeyPath:nil cacheName:@"Root"];

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

    [aFetchedResultsController release];
    [fetchRequest release];
    [sortDescriptor release];
    [sortDescriptors release];

    return fetchedResultsController;
}
                                                         

The first part of the code should be familiar. It checks to see if you have already created the fetchedResultsController. If it already exists, the method returns the controller. If not, the code goes on to create it.

The next section of code creates and configures the objects needed by the fetchedResultsController. As you can see from Figure 5-4, you need a fetch request and a context to be able to use the fetchedResultsController. Because you already have a context, in the managedObjectContext property, the code only needs to create a fetch request.

You can think of a fetch request as a SQL SELECT statement. The code creates a FetchRequest object, creates an entity based on the "Event" entity in the context, and then sets the entity used by the fetchRequest. Next, the code sets the batch size of the fetchRequest to a reasonable number of records to receive at a time.

The next bit of code creates an NSSortDescriptor. You use the NSSortDescriptor to sort the results in the fetchRequest. You can think of the NSSortDescriptor as a SQL ORDER BY clause. Here, you order the result set based on the timeStamp field in descending order. The NSSortDescriptor then sets the sort descriptor used by the fetch request.

Finally, calling the initWithFetchRequest:managedObjectContext:sectionNameKeyPath:cacheName: method creates and initializes fetchedResultsController. The template then sets the delegate to self, assigns the fetchedResultsController property, and then the template releases the local objects.

The only delegate method from the NSFetchedResultsControllerDelegate protocol implemented by the template is controllerDidChangeContent:. The fetchedResultsController calls this method when all changes to the objects managed by the controller are complete. In this case, you tell the table to reload its data.

- (void)controllerDidChangeContent:(NSFetchedResultsController *)controller {
    // In the simplest, most efficient, case, reload the table view.
    [self.tableView reloadData];
}
                                                         

Now that you have seen how you create and configure the fetchedResultsController, let's look at how you configure the RootViewController at startup. You do this in the viewDidLoad method:

- (void)viewDidLoad {
    [super viewDidLoad];

    // Set up the edit and add buttons.
    self.navigationItem.leftBarButtonItem = self.editButtonItem;

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

    self.navigationItem.rightBarButtonItem = addButton;
    [addButton release];

    NSError *error = nil;
    if (![[self fetchedResultsController] performFetch:&error]) {
        //  Log the error
        NSLog(@"Unresolved error %@, %@", error, [error userInfo]);

        //  Quit
        abort();
    }
}
                                                         

The method first calls the superclass version of viewDidLoad to ensure that you perform any initialization required by the superclass.

Next, the code configures the Edit button, creates the Add button and adds the buttons to the navigation at the top of the screen. You can see in the initialization of the addButton that the insertNewObject method will be called when someone taps the Add button.

Finally, you call the performFetch: method on the fetchedResultsController to execute the fetch request and retrieve the desired data.

Now, you will look at how you use the TableView delegate methods to display your data. These should be familiar to you from Chapter 3.

The first method is numberOfSectionsInTableView:.

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

As you may recall, the TableView calls this method when it needs to know how many sections to display. Here, the code simply asks the fetchedResultsController for the number of sections.

The next TableView delegate method is numberOfRowsInSection:.

- (NSInteger)tableView:(UITableView *)tableView
    numberOfRowsInSection:(NSInteger)section {

    id <NSFetchedResultsSectionInfo> sectionInfo =
        [[fetchedResultsController sections] objectAtIndex:section];
    return [sectionInfo numberOfObjects];
}
                                                         

Again, you call upon the fetchedResultsController to return the number of rows to display.

Finally, you configure the cell in the cellForRowAtIndexPath: method.

- (UITableViewCell *)tableView:(UITableView *)tableView
         cellForRowAtIndexPath:(NSIndexPath *)indexPath {

    static NSString *CellIdentifier = @"Cell";

    UITableViewCell *cell = [tableView
                             dequeueReusableCellWithIdentifier:CellIdentifier];
    if (cell == nil) {
        cell = [[[UITableViewCell alloc]
                 initWithStyle:UITableViewCellStyleDefault
                 reuseIdentifier:CellIdentifier] autorelease];
    }

// Configure the cell.
    NSManagedObject *managedObject = [fetchedResultsController
                                      objectAtIndexPath:indexPath];
    cell.textLabel.text =
        [[managedObject valueForKey:@"timeStamp"] description];

    return cell;
}
                                                         

This code should be familiar down to the point where it retrieves the managed object. Again, the code asks fetchedResultsController for the object pointed to by the index path. Once it obtains this object, the code uses key-value coding to get the value for the timeStamp property. You learn more about key-value coding in Chapter 6.

The commitEditingStyle:forRowAtIndexPath: method contains the code to handle editing rows in the TableView. The TableView calls this method when editing of the TableView will cause a change to the underlying data. In this case, deleting an object in the TableView should delete the object from the context.

- (void)tableView:(UITableView *)tableView
    commitEditingStyle:(UITableViewCellEditingStyle)editingStyle
    forRowAtIndexPath:(NSIndexPath *)indexPath {

    if (editingStyle == UITableViewCellEditingStyleDelete) {
        // Delete the managed object for the given index path
        NSManagedObjectContext *context =
            [fetchedResultsController managedObjectContext];

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

        // Save the context.
        NSError *error = nil;
        if (![context save:&error]) {
            NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
            abort();
        }
    }
}
                                                         

The code first determines if the user has deleted a cell. Then, it gets a reference to the context and tells the context to delete the object that was deleted from the TableView. Last, the context changes are committed to disk by calling the save: method.

The last interesting bit of code in the RootViewController is the insertNewObject method. Recall that this is the method that will be called when a user taps the Add button at the top of the screen.

- (void)insertNewObject {

    // Create a new instance of the entity managed by the fetched results
    // controller.
    NSManagedObjectContext *context =
        [fetchedResultsController managedObjectContext];
    NSEntityDescription *entity =
        [[fetchedResultsController fetchRequest] entity];
    NSManagedObject *newManagedObject =
        [NSEntityDescription insertNewObjectForEntityForName:[entity name]
                                      inManagedObjectContext:context];

    // If appropriate, configure the new managed object.
    [newManagedObject setValue:[NSDate date] forKey:@"timeStamp"];

    // Save the context.
    NSError *error = nil;
    if (![context save:&error]) {
        NSLog(@"Unresolved error %@, %@", error, [error userInfo]);
        abort();
    }
}
                                                         

Like the commitEditingStyle:forRowAtIndexPath: method, this code first gets a reference to the context. Next, the code creates a new entity based on the entity that the fetchedResultsController uses. The code then creates a new managed object based on that entity and inserts it into the context. Next, the code configures the managed object with the appropriate data; in this case, a timestamp. Finally, the context is committed to disk with the save: method.