The Core iOS Developer’s Cookbook, Fifth Edition (2014)

Chapter 12. A Taste of Core Data

iOS’s Core Data framework provides persistent data solutions. Your applications can query and update Core Data’s managed data stores. With Core Data, you gain a Cocoa Touch–based object interface that brings relational data management out from SQL queries and into the Objective-C world of iOS development. Core Data delivers the perfect technology to power your table view and collection view instances.

This chapter introduces Core Data. It provides just enough how-to to give you a taste of the technology, offering a jumping-off point for further Core Data learning. By the time you finish reading through this chapter, you’ll have seen Core Data for iOS in action and gotten an overview of the technology.

Introducing Core Data

Core Data simplifies the way your applications create and use persisted objects, known as managed objects. Until the 3.x SDK, all data management and SQL access were left to a fairly low-level library. It wasn’t pretty, and it wasn’t easy to use. Since then, Core Data has joined the Cocoa Touch framework family, bringing powerful data management solutions to iOS. Core Data provides a flexible infrastructure, offering tools for working with persistent data stores and generating solutions for the complete object life cycle.

Core Data lives in the model portion of the Model–View–Controller (MVC) paradigm. It understands that application-specific data must be defined and controlled outside the application’s GUI, even as it powers that interface. Core Data integrates beautifully with table view and collection view instances. Cocoa Touch’s fetched-results controller class was designed and built with these kinds of classes in mind. It offers useful properties and methods that support data source and delegate integration.

Entities and Models

Entities live at the top of the Core Data hierarchy. They describe objects stored inside your database. Entities provide the virtual cookie cutters that specify how each data object is created. When you build new objects, entities detail the attributes and relationships that make up each object. Every entity has a name, which Core Data uses to retrieve entity descriptions as your application runs.

You build entities inside model files. Each project that links against the Core Data framework includes one or more model files. These .xcdatamodeld files define entities, their attributes, and their relationships.

Building a Model File

Create your model in Xcode by laying out a new data model file. Some iOS templates allow you to include Core Data as part of the project. Otherwise, you create these Xcode model files by selecting File > New > File from the Xcode menu and then choosing iOS, Core Data, Data Model, and Next. Enter a name for your new file (this example uses Person), check the targets for your project, and click Save. Xcode creates and then adds the new model file to your project (for example, Person.xcdatamodeld). Click the xcdatamodeld file in the File Navigator to open it in the editor window shown in Figure 12-1.

Figure 12-1 Xcode’s editor enables you to build managed object definitions for your Core Data applications.

You add new entities (basically classes of objects) to the left list in the editor window by clicking the Add Entity button near the bottom left. Add attributes (essentially instance variables for entities) by clicking the Add Attribute button at the bottom right. Double-click any individual entity or attribute name to change it; use the Type pop-up to set an attribute’s type.

Use the center portion of the editor to customize your attributes and relationships. Relationships are the optional ways entities relate to each other in the database. An inspector to the right provides context-specific settings. In Figure 12-1, it’s showing details for the Person entity’semailaddress attribute.

The Entity editor provides two layout styles. Toggle between the table view and an object graph by tapping the Editor Style buttons at the bottom right of the editor pane.

The detail table style shown in Figure 12-1 provides a list of each entity, attribute, and relationship defined in the model. The object graph offers a grid-based visual presentation of the entities you have defined, allowing you to visualize and edit entity relationships—the way entities relate to each other. For example, a parent can have several children and one spouse. A department may include members, and a manager may serve on several committees.

Attributes and Relationships

Each entity may include attributes, which store information such as a name, a birth date, a designation, and so forth. The Objective-C object that corresponds to an entity expresses properties defined by these attributes.

Each entity may also define relationships, which are links between one object and another. These relationships can be single, using a one-to-one relationship (spouse, employer), or they can be multiple (children, credit card accounts), using a one-to-many relationship. In addition, relationships should be reciprocal, providing an inverse relationship (my child, his parent).

Select an entity to start adding attributes. With the entity selected, tap the Add Attribute button at the bottom right of the editor pane. (Or tap and hold this button to choose either Add Attribute, Add Relationship, or Add Fetched Property.) Each attribute has a name and a data type, just as you would define an instance variable.

Relationships provide pointers to other objects. When working with the Graph editor, you can Control-drag to create them. Arrows represent the relationships between the various kinds of entities in a project.

At the simplest level, you can work with just one entity and without relationships, even though Core Data offers a fully powered relational database. Most iOS applications do not require a high level of sophistication. A flat database with section attributes is all you need to power table views and collection views.

To build the model in Figure 12-1, create a Person entity and add these seven attributes: emailaddress, gender, givenname, middleinitial, occupation, surname, and section. Set each type to String.

Building Object Classes

After creating your entity definition, save your changes to the data model file. Select an entity in the column on the left and from the Xcode menu, choose Editor > Create NSManagedObject Subclass. Select your data model and the entity (or entities) you intend to manage. Save to your project folder, select the group you want to add the classes to, and click Create. Xcode generates class files from your entity description. Here is what the automatically generated Person class looks like:

@interface Person : NSManagedObject

@property (nonatomic, strong) NSString *section;
@property (nonatomic, strong) NSString *emailaddress;
@property (nonatomic, strong) NSString *gender;
@property (nonatomic, strong) NSString *givenname;
@property (nonatomic, strong) NSString *middleinitial;
@property (nonatomic, strong) NSString *occupation;
@property (nonatomic, strong) NSString *surname;

@end

@implementation Person

@dynamic section;
@dynamic emailaddress;
@dynamic gender;
@dynamic givenname;
@dynamic middleinitial;
@dynamic occupation;
@dynamic surname;

@end

Each attribute corresponds to a string property. When you use other attribute types, their properties correspond accordingly (for example, NSDate, NSNumber, NSData). If you were to add a one-to-many relationship, you’d see a set. The @dynamic directive creates property accessors at runtime.

Creating Contexts

In Core Data, entities provide descriptions. Objects are actual class instances that you create from entity specifications. These instances all descend from the NSManagedObject class and represent entries in the database.

Core Data objects live within a managed object context. These contexts, which are instances of NSManagedObjectContext, each represent an object space within your application. This chapter uses a single object context, although more complex implementations may be required in your own apps, primarily to support multithreaded Core Data access.

In this single-object-context example, you establish your context as you start up your application and use that context for all object fetch requests from the stored data. The context story begins by loading any models you have created from the application bundle. You do not need to specify any names:

// Init the model
NSManagedObjectModel *managedObjectModel =
[NSManagedObjectModel mergedModelFromBundles:nil];

Next, create a store coordinator and connect it to a file (a store) in the app sandbox. The coordinator manages the relationship between the managed object model in your application and a local file. You provide a file URL that specifies where to save the data. This snippet usesNSSQLiteStoreType, which creates a file using the standard SQLite binary format:

// Create the store coordinator
NSPersistentStoreCoordinator *persistentStoreCoordinator =
[[NSPersistentStoreCoordinator alloc]
initWithManagedObjectModel:managedObjectModel];

// Connect to the data store (on disk)
NSURL *url = [NSURL fileURLWithPath:dataPath];
if (![persistentStoreCoordinator
addPersistentStoreWithType: NSSQLiteStoreType
configuration:nil URL:url options:nil error:&error])
{
NSLog(@"Error creating persistent store coordinator: %@",
error.localizedFailureReason);
return;
}

Finally, you create the actual context and set a property to the coordinator you just created:

// Create a context and assign to the context property
_context = [[NSManagedObjectContext alloc] init];
_context.persistentStoreCoordinator = persistentStoreCoordinator;

Adding Data

The NSEntityDescription class enables you to insert new objects into your context. This lets you add new data entries to populate your file. Provide an entity name and the context you’re working with:

// Create new object
- (NSManagedObject *)newObject
{
NSManagedObject *object = [NSEntityDescription
insertNewObjectForEntityForName:_entityName
inManagedObjectContext:_context];
return object;
}

The request returns a new managed object for you to work with. After you receive the new managed object, you customize it however you like and then save the context:

// Save
- (BOOL)save
{
NSError __autoreleasing *error;
BOOL success;
if (!(success = [_context save:&error]))
NSLog(@"Error saving context: %@", error.localizedFailureReason);
return success;
}

A typical call pattern goes like this: Create one or more new objects, set their properties, and save. You could use the above methods to insert a new Person entity in the database as follows:

Person *person = (Person *)[dataHelper newObject];
person.givenname = @"Chris";
person.surname = @"Zahn";
person.section = [[person.surname substringFromIndex:0] substringToIndex:1];
person.occupation = @"Editor";
[dataHelper save]

Notice that the section property here derives from the surname. In nearly every basic iOS application, you’ll want to add a section property to allow Core Data to group entries together by some common connection. The property name does not matter; you pass it as an argument.section is easy to recognize and remember. Advanced users will write a method to provide their grouping criteria instead of hard-coding it as this example does.

This snippet creates a group-by-surname-initial approach. When you want to group by some other property, either iterate through your data to update the property you use for sections or supply a different attribute to your fetch request. This flexibility makes it easy to change from grouping by last initial to grouping by occupation. A section later in this chapter discusses fetch requests and querying your Core Data store.

Don’t confuse iOS sections (used for table views and collection views) with sorting, which is another concept you encounter with Core Data. Sections specify groupings within your object collection. Sorting controls how items are ordered within each section.

Examining the Data File

If you run the preceding code in the simulator, you can easily inspect the SQLite file that Core Data creates. Navigate to the simulator folder (~/Library/Application Support/iPhone Simulator/Firmware/Applications, where Firmware is the current firmware release; for example, 7.0) and then into the folder for the application itself.

Stored in the Documents folder (depending on the URL used to create the persistent store), an SQLite file contains the database representation you’ve created. The command-line sqlite3 utility enables you to inspect the contents by performing a .dump operation:

% sqlite3 Person.sqlite
SQLite version 3.7.13 2012-07-17 17:46:21
Enter ".help" for instructions
Enter SQL statements terminated with a ";"
sqlite> .dump
PRAGMA foreign_keys=OFF;
BEGIN TRANSACTION;
CREATE TABLE ZPERSON ( Z_PK INTEGER PRIMARY KEY, Z_ENT INTEGER, Z_OPT INTEGER,
ZEMAILADDRESS VARCHAR, ZGENDER VARCHAR, ZGIVENNAME VARCHAR, ZMIDDLEINITIAL VARCHAR,
ZOCCUPATION VARCHAR, ZSECTION VARCHAR, ZSURNAME VARCHAR );
INSERT INTO "ZPERSON" VALUES(1,1,1,'ChristopherLRobinson@foomail.com','male','Christop
her','L','Home care aide','C','Robinson');
INSERT INTO "ZPERSON" VALUES(2,1,1,'NicholasJGrant@spambob.com','male','Nicholas','J',
'Steadicam operator','N','Grant');
INSERT INTO "ZPERSON" VALUES(3,1,1,'JosephJTreece@spambob.
com','male','Joseph','J','Shoe machine operator','J','Treece');
INSERT INTO "ZPERSON" VALUES(4,1,1,'HelenEShaffer@dodgit.
com','female','Helen','E','Coin vending and amusement machine servicer
repairer','H','Shaffer');
CREATE TABLE Z_PRIMARYKEY (Z_ENT INTEGER PRIMARY KEY, Z_NAME VARCHAR, Z_SUPER INTEGER,
Z_MAX INTEGER);
INSERT INTO "Z_PRIMARYKEY" VALUES(1,'Person',0,3000);
CREATE TABLE Z_METADATA (Z_VERSION INTEGER PRIMARY KEY, Z_UUID VARCHAR(255), Z_PLIST
BLOB);
INSERT INTO "Z_METADATA" VALUES(1,'85E928DB-1464-4C3B-BCEA-
9277B8817A04',X'62706C6973743030D601020304050607090A0D0E0F5F101E4E5353746F72654D6F646
56C56657273696F6E4964656E746966696572735F101D4E5350657273697374656E63654672616D65776F
726B56657273696F6E5F10194E5353746F72654D6F64656C56657273696F6E4861736865735B4E5353746
F7265547970655F10125F4E534175746F56616375756D4C6576656C5F10204E5353746F72654D6F64656C
56657273696F6E48617368657356657273696F6EA1085011019AD10B0C56506572736F6E4F1020D261E38
54795D61A5D69048846ECC3DCFEAC4861D9FCD1540A071C875FE89EA95653514C69746551321003081536
56727E93B6B8B9BCBFC6E9F0F200000000000001010000000000000010000000000000000000000000000
000F4');
COMMIT;
sqlite> .quit
%

Here you see several SQL table definitions that store the information for each object plus the insert commands used to store the instances built in your code. Although you are thoroughly cautioned against directly manipulating the Core Data store with sqlite3, it offers a valuable insight into what’s going on under the Core Data hood.

Querying the Database

Retrieve objects from the database by performing fetch requests. A fetch request describes your search criteria for selecting objects. It’s passed through to Core Data and used to initialize a results object that contains an array of fetched objects that meet those criteria. Here is a sample fetch method that saves the resulting fetched results to a local instance variable (_fetchedResultsController) associated with a helper class property:

- (void)fetchItemsMatching:(NSString *)searchString
forAttribute:(NSString *)attribute
sortingBy:(NSString *)sortAttribute
{
// Build an entity description
NSEntityDescription *entity = [NSEntityDescription
entityForName:_entityName inManagedObjectContext:_context];

// Init a fetch request
NSFetchRequest *fetchRequest = [[NSFetchRequest alloc] init];

fetchRequest.entity = entity;
[fetchRequest setFetchBatchSize:0];

// Apply an ascending sort for the items
NSString *sortKey = sortAttribute ? : _defaultSortAttribute;
NSSortDescriptor *sortDescriptor = [[NSSortDescriptor alloc]
initWithKey:sortKey ascending:YES selector:nil];
NSArray *descriptors = @[sortDescriptor];
fetchRequest.sortDescriptors = descriptors;

// Optional setup predicate
if (searchString && attribute) fetchRequest.predicate =
[NSPredicate predicateWithFormat:@"%K contains[cd] %@",
attribute, searchString];

// Perform the fetch
NSError __autoreleasing *error;
_fetchedResultsController = [[NSFetchedResultsController alloc]
initWithFetchRequest:fetchRequest managedObjectContext:_context
sectionNameKeyPath:@"section" cacheName:nil];
if (![_fetchedResultsController performFetch:&error])
NSLog(@"Error fetching data: %@", error.localizedFailureReason);
}

Setting Up the Fetch Request

A fetch request describes how you want to search through data. This process starts by retrieving an entity description for a given entity name. For the Person entity, that name is @"Person". The description specifies what kinds of data you want to search for.

Create a new fetch request, initializing it with the entity description you just retrieved and a batch size. A 0 batch size corresponds to an indefinite request. If you want to limit the number of returned results, set the batch size to a positive number.

Each request must contain at least one sort descriptor. This method sorts in ascending order (ascending:YES), using a sort key. As with the entity name, the sort key is a string (for example, @"surname"). Set the fetch request’s sortDescriptors property with an array of descriptors.

Fetch requests use optional predicates to narrow the results to items that match certain rules. When callers supply the appropriate searchString and attribute parameters, this method creates a predicate of the form attribute contains[cd] searchString.

This form creates a non-case-sensitive text match; the [cd] after contains refers to non-case-sensitive and non-diacritic-sensitive matching. Diacritics are small marks that accompany a letter, such as the dots of an umlaut (¨) or the tilde (~) above a Spanish n.

The %@ format includes an item directly in the predicate, such as the search string used here. The %K format specifies an entity attribute. If you fail to use it, the predicate 'surname' contains[cd] 'u' will always return true because the second letter in surname is u. Use %K to match the property, not the name of the property.

For more complex queries, you could assign a compound predicate. Compound predicates allow you to combine simple predicates using standard logical operations such as AND, OR, and NOT. The NSCompoundPredicate class builds compound predicates out of component predicates. You can also skip the compound predicate class and include AND, OR, and NOT notation directly in simple NSPredicate text.