NSFetchedResultsController Class Reference

Overview

This class is intended to efficiently manage the results returned from a Core Data fetch request to provide data for a UITableView object.

You use this class to populate cells in a UITableView object with objects fetched from Core Data. While table views can be used in several ways, this object is primarily intended to assist you with a master list view. UITableView expects its data source to provide cells as an array of sections made up of rows. You configure an instance of this class using a fetch request that specifies the entity, an array containing at least one sort ordering, and optionally a filter predicate. NSFetchedResultsController efficiently analyzes the result of the fetch request and computes all the information about sections in the result set, and for the index.

In addition, NSFetchedResultsController provides the following features:

• It optionally monitors changes to objects in its associated managed object context, and reports changes in the results set to its delegate (see “The Controller’s Delegate”).

• It optionally caches the results of its computation so that if the same data is subsequently re-displayed, the work does not have to be repeated (see “The Cache”).

A controller thus effectively has three modes of operation, determined by whether it has a delegate and whether the cache file name is set.

1. No tracking: the delegate is set to nil.

   The controller simply provides access to the data as it was when the fetch was executed.

2. Memory-only tracking: the delegate is non-nil and the file cache name is set to nil.

   The controller monitors objects in its result set and updates section and ordering information in response to relevant changes.

3. Full persistent tracking: the delegate and the file cache name are non-nil.

   The controller monitors objects in its result set and updates section and ordering information in response to relevant changes. The controller maintains a persistent cache of the results of its computation.

Using NSFetchedResultsController

Creating the Fetched Results Controller

You typically create an instance of NSFetchedResultsController as an instance variable of a table view controller. You configure the controller with a fetch request, which must contain at least one sort descriptor to order the results. You can specify as the sectionNameKeyPath argument a key that the controller will use to split the results into sections, or pass nil to indicate that the controller should generate a single section. After creating an instance, you invoke performFetch: to actually execute the fetch.

NSManagedObjectContext *context = <#Managed object context#>;

NSFetchRequest *fetchRequest = [[NSFetchRequest alloc] init];

// Configure the request's entity, and optionally its predicate.

NSSortDescriptor *sortDescriptor = [[NSSortDescriptor alloc] initWithKey:@"<#Sort key#>" ascending:YES];

NSArray *sortDescriptors = [[NSArray alloc] initWithObjects:sortDescriptor, nil];

[fetchRequest setSortDescriptors:sortDescriptors];

[sortDescriptors release];

NSFetchedResultsController *controller = [[NSFetchedResultsController alloc]

        initWithFetchRequest:fetchRequest

        managedObjectContext:context

        sectionNameKeyPath:nil

        cacheName:@"<#Cache name#>"];

[fetchRequest release];

NSError *error;

BOOL success = [controller performFetch:&error];

The Controller’s Delegate

If you set a delegate for a fetched results controller, the controller registers to receive change notifications from its managed object context. Any change in the context that affects the result set or section information is processed and the results are updated accordingly. The controller notifies the delegate when result objects change location or when sections are modified (see NSFetchedResultsControllerDelegate). You typically use these methods to update the display of the table view.

The Cache

Where possible, a controller uses a cache to avoid the need to repeat work performed in setting up any sections and ordering the contents. The cache is maintained across launches of your application.

When you initialize an instance of NSFetchedResultsController, you typically specify a cache name. (If you do not specify a cache name, the controller does not cache data.) When you create a controller, it looks for an existing cache with the given name:

• If the controller can’t find an appropriate cache, it calculates the required sections and the order of objects within sections. It then writes this information to disk.

• If it finds a cache with the same name, the controller tests the cache to determine whether its contents are still valid. The controller compares the current entity name, entity version hash, sort descriptors, section key-path, and total object count with those stored in the cache, as well as the modification date of the cached information file and the persistent store file.

  If the cache is consistent with the current information, the controller reuses the previously-computed information.

  If the cache is not consistent with the current information, then the required information is recomputed, and the cache updated.

Any time the section and ordering information change, the cache is updated.

If you have multiple fetched results controllers with different configurations (different sort descriptors and so on), you must give each a different cache name.

You can purge a cache using deleteCacheWithName:.

Implementing the Table View Datasource Methods

You ask the object to provide relevant information in your implementation of the table view data source methods:

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {

    return [[<#Fetched results controller#> sections] count];

}

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

    id <NSFetchedResultsSectionInfo> sectionInfo = [[<#Fetched results controller#> sections] objectAtIndex:section];

    return [sectionInfo numberOfObjects];

}

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

    UITableViewCell *cell = <#Get the cell#>;

    NSManagedObject *managedObject = [<#Fetched results controller#> objectAtIndexPath:indexPath];

    // Configure the cell with data from the managed object.

    return cell;

}

- (NSString *)tableView:(UITableView *)tableView titleForHeaderInSection:(NSInteger)section { 

    id <NSFetchedResultsSectionInfo> sectionInfo = [[<#Fetched results controller#> sections] objectAtIndex:section];

    return [sectionInfo name];

}

- (NSArray *)sectionIndexTitlesForTableView:(UITableView *)tableView {

    return [<#Fetched results controller#> sectionIndexTitles];

}

- (NSInteger)tableView:(UITableView *)tableView sectionForSectionIndexTitle:(NSString *)title atIndex:(NSInteger)index {

    return [<#Fetched results controller#> sectionForSectionIndexTitle:title atIndex:index];

}

- (NSInteger)numberOfSectionsInTableView:(UITableView *)tableView {

    NSUInteger count = [[<#Fetched results controller#> sections] count];

    if (count == 0) {

        count = 1;

    }

    return count;

}

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

    NSArray *sections = [<#Fetched results controller#> sections];

    NSUInteger count = 0;

    if ([sections count]) {

        id <NSFetchedResultsSectionInfo> sectionInfo = [sections objectAtIndex:section];

        count = [sectionInfo numberOfObjects];

    }

    return count;

}

Responding to User-Driven Changes

In general, NSFetchedResultsController is designed to respond to changes at the model layer by informing its delegate when result objects change location or when sections are modified. If you allow a user to reorder table rows, then your implementation of the delegate methods must take this into account—see NSFetchedResultsControllerDelegate. There is also a limitation that NSFetchedResultsController does not support sections being deleted as a result of a UI-driven change.

Subclassing Notes

You create a subclass of this class if you want to customize the creation of sections and index titles. You override sectionIndexTitleForSectionName: if you want the section index title to be something other than the capitalized first letter of the section name. You override sectionIndexTitles if you want the index titles to be something other than the array created by calling sectionIndexTitleForSectionName: on all the known sections.