iphone programming: core data tutorial for ios

Core Data Tutorial foriOS

Contents

Introduction 5Organization of This Document 6

Starting Out 7Create the Project 8Understanding a Core Data–Based Project 9The Core Data Stack 9

Managed Objects and the Managed Object Context 10The Managed Object Model 11Persistent Store Coordinator 12

The Table View Controller 14Creating and Defining the RootViewController Class 14Implementing the RootViewController Class 15

Synthesize the Properties 16Write the Accessor Method for the Core Location Manager 16Implementing viewDidLoad 17Implement Methods for Memory Management 18

Configuring the Application Delegate 18Add the Navigation Controller Property 18Implement the Application Delegate 19

Build and Test 20

Managed Object and Model 22Modeling Your Data 22

Add the Entity 22Add the Attributes 23

Custom Managed Object Class 25Core Data Recap 26

Adding Events 27Implementing the addEvent Method 27

Get the Current Location 27Create and Configure the Event object 28

2012-12-13 | © 2012 Apple Inc. All Rights Reserved.

2

Save the New Event 28Handling Errors 29Update the Events Array and the Table View 29

Displaying Events in the Table View 30Build and Test 32Core Data Recap 32

Fetching Events 33Fetching Managed Objects 33Creating and Executing the Request 34

Create the Request 34Set the Sort Descriptor 35Execute the Request 35Finish Up 36

Build and Test 36Core Data Recap 36

Deleting Events 37Deleting Managed Objects 37Deleting an Event 37Build and Test 38Core Data Recap 38

Next Steps 40The Core Data Utility Tutorial 40Use a Fetched Results Controller 40Creating a Managed Object Model with Xcode 40A Drill-Down Interface 41Add an Add Sheet 41

Document Revision History 42


3

Contents

Figures

Starting Out 7Figure 1-1 A simple Core Data stack 10Figure 1-2 Managed objects in a context, and a table in the persistent store 11Figure 1-3 An entity description, a table in the database, and a managed object. 11Figure 1-4 A complex Core Data stack 13


4

Core Data is a schema-driven object graph management and persistence framework. Fundamentally, CoreData helps you to save model objects (in the sense of the model-view-controller design pattern) to a file andget them back again. This is similar to archiving (see Archives and Serializations Programming Guide ), but CoreData offers much more than that. Amongst other things, it:

● Provides an infrastructure for managing all the changes to your model objects. This gives you automaticsupport for undo and redo, and for maintaining reciprocal relationships between objects.

● Allows you to keep just a subset of your model objects in memory at any given time. This is especiallyimportant on iOS where conserving memory is critical.

● Uses a schema to describe the model objects. You define the principal features of your modelclasses—including the relationships between them—in a GUI-based editor. This provides a wealth of basicfunctionality “for free,” including setting of default values and attribute value validation.

● Allows you to maintain disjoint sets of edits of your objects. This is useful if you want to, for example, allowthe user to make edits in one view that may be discarded without affecting data displayed in anotherview.

● Has an infrastructure for data store versioning and migration. This lets you easily upgrade an old versionof the user’s file to the current version.

Core Data is available on iOS 3.0 and later.

You should read this document to learn how to use Core Data on iOS, including:

● The fundamental design patterns and techniques that underlie Core Data

● The basics of using the Xcode data modeling tool

● How to create, update, and delete objects managed by Core Data, and how to commit changes to a datastore


5

Introduction

Important: Core Data is not an entry-level technology. Before starting to use Core Data, you must understandthe basics of iOS application development, including:

● How to use Xcode and Interface Builder

● Fundamental design patterns such as model-view-controller and delegation

● How to use view controllers, navigation controllers, and table views

None of these tools and techniques are explained in this tutorial, so that the content can focus on CoreData itself.

Documents you should read to gain adequate experience include: ● Your First iOS App

● Xcode Workspace Guide

● Cocoa Fundamentals Guide

● View Controller Programming Guide for iOS

● Table View Programming Guide for iOS

Organization of This DocumentThis tutorial comprises the following chapters:

● “Starting Out” (page 7)

● “The Table View Controller” (page 14)

● “Managed Object and Model” (page 22)

● “Adding Events” (page 27)

● “Fetching Events” (page 33)

● “Deleting Events” (page 37)

● “Next Steps” (page 40)

The source code for the tutorial is provided in the Locations sample code.

IntroductionOrganization of This Document


6

The goals of this chapter are to describe the application that you will build, then to create the Xcode projectand to understand the basics of what the Xcode project template gives you.

The goal of this tutorial is to provide a practical introduction to the Core Data framework and how you use it.

The aim here is not to create a polished application, but rather to illustrate the fundamental classes, tools, andtechniques you’ll use in any Core Data–based program. It doesn’t provide in-depth explanations of all thefeatures the framework offers, but it does give references to other documents you can read to gain a deeperunderstanding.

To add a bit more interest, the tutorial also makes use of the Core Location framework. The Core Locationmanager is a straightforward object, and for the purposes of this project you don’t need to understand it inany detail.

The application you create is conceptually simple—it lets you record your location at any time as an “event,”and uses a table view to show the time, latitude, and longitude of all the events you’ve recorded. It has an Addbutton to add a new event, and an Edit button that allows you to delete events from the list.


7

Starting Out

In this tutorial, you use Core Data primarily to represent the Event objects and store them in an external fileso that they can be displayed when the application launches.

Note: As a convention,>> denotes the beginning of a paragraph (sometimes including the followingbulleted list) that contains steps that you must perform in the tutorial.

In code listings, comments included in Xcode template files are not shown.

Create the ProjectThe only steps in this chapter are to create the project itself and link against the Core Location framework.

>> In Xcode, create a Project using the Window-Based Application template in the iOS section. In the Optionssection, select the switch to use Core Data for storage. Call the project “Locations”.

It’s important that you call the project “Locations” if you want to copy and paste code required later in thetutorial.

>> link the project against the Core Location framework.

Starting OutCreate the Project


8

Understanding a Core Data–Based ProjectTogether with various other supporting files, the template provides you with:

● An application delegate class

● A MainWindow interface (.xib) file

● A Core Data model (.xcdatamodeld) file—typically referred to as the managed object model

The application also links against the Core Data framework.

Of the resources, the first two should be familiar, although the details of the delegate class will be new. Themodel file is described later in “Managed Object and Model” (page 22). For now, examine the header file ofthe application delegate class. In addition to the standard window and view controller, it provides (amongstother features) three properties and two methods:

@property (nonatomic, retain, readonly) NSManagedObjectContext *managedObjectContext;

@property (nonatomic, retain, readonly) NSManagedObjectModel *managedObjectModel;

@property (nonatomic, retain, readonly) NSPersistentStoreCoordinator*persistentStoreCoordinator;

- (NSURL *)applicationDocumentsDirectory;

- (void)saveContext;

As its name implies, the applicationDocumentsDirectory method simply returns the URL identifying theapplication’s documents directory, which is where the file containing the application’s data will be located.The properties provide access to what’s called the Core Data stack, and saveContext saves changes you maketo model objects to the data file.

The Core Data StackStack is the term used to describe a collection of Core Data framework objects that work together to getmodeled objects from and save data to a persistent store—the file where your data is stored. Conceptually,a persistent store is like a database, with tables and records. (One of the store types you can use with CoreData is SQLite, but the store doesn’t have to be an actual database.)

Starting OutUnderstanding a Core Data–Based Project


9

Figure 1-1 (page 10) shows the simplest—and most common—configuration of the stack.

Figure 1-1 A simple Core Data stack

StoreFile

Persistent Object Store

A collection of object data

Managed Object Model

A collection of entity descriptions

Managed Object Context

A collection of managed objects

Persistent Store Coordinator

A collection of stores

The objects you usually work directly with are at the top of the stack—the managed object context and themanaged objects it contains.

Managed Objects and the Managed Object ContextA managed object is an instance of NSManagedObject or of a subclass of NSManagedObject. Conceptually,it’s an object representation of a record in a table in a database, so it’s a model (in the sense of themodel-view-controller design pattern) object that is managed by Core Data. Managed objects represent the datayou operate on in your application—for example departments and employees in a human resources application;shapes, text areas, and groups in a drawing application; albums, artists, and tracks in a music managementapplication. A managed object is always associated with a managed object context.

The managed object context is an instance of NSManagedObjectContext. A context represents a singleobject space, or scratch pad, in an application. Its primary responsibility is to manage a collection of managedobjects. These objects form a group of related model objects that represent an internally consistent view ofone or more persistent stores. The context is a powerful object with a central role in your application, withresponsibilities from life-cycle management to validation, relationship maintenance, and undo/redo.

When you create a new managed object, you insert it into a context. You fetch existing records in the databaseinto the context as managed objects. (Fetching is discussed in greater detail in “Fetching Events” (page 33).)Any changes you make (whether insertion or deletion of complete objects, or manipulation of property values)are kept in memory until you actually commit them to the store by saving the context.

Starting OutThe Core Data Stack


10

Figure 1-2 (page 11) illustrates a managed object context that contains two managed objects correspondingto two records in an external database. In one of the objects, a property value has been changed in memory,but the change has not been committed to the database. Notice that there are two additional records in thedatabase for which there are no corresponding managed objects.

Figure 1-2 Managed objects in a context, and a table in the persistent store


Employeenamesalary

Fred90000

Employeenamesalary

Nigel60000 Unsaved data

nameFred

salary9000097000

Nigel 50000Tanya 56000

Employee

JuliCurrent data

The Managed Object ModelA managed object model is an instance of NSManagedObjectModel. It’s an object representation of a schemathat describes your database, and so the managed objects you use in your application. A model is a collectionof entity description objects (instances of NSEntityDescription). An entity description describes an entity(a table in a database) in terms of its name, the name of the class used to represent the entity in your application,and what properties (attributes and relationships) it has.

Figure 1-3 (page 11) illustrates the relationship between an entity description in a model, a table in the database,and a managed object corresponding to a single record in the table.

Figure 1-3 An entity description, a table in the database, and a managed object.

Managed Objectnamesalary

Fred97000

entityDescription

Entity DescriptionNameManaged Object ClassAttributeAttribute

“Employee”NSManagedObjectnamesalary



11

Every managed object has a reference to the entity of which it is an instance.

Core Data uses the model to map between managed objects in your application and records in the database.It’s important to be aware that if you change the schema in your application, Core Data won’t be able to readstores you created using the previous model. (This is something common to many persistence mechanisms.Core Data, though, does also provide an infrastructure for managing such changes—see the Core Data ModelVersioning and Data Migration Programming Guide .)

Persistent Store CoordinatorThe persistent store coordinator plays a central role in how Core Data manages data; however, you don’toften interact with the coordinator directly when you use the framework. This section describes the persistentstore coordinator in detail, so if you prefer you can skip it and refer to it later as necessary. (The persistent storecoordinator is also described in “Core Data Basics” in the Core Data Programming Guide .)

A persistent store coordinator is an instance of NSPersistentStoreCoordinator. It manages a collectionof persistent object stores. A persistent object store represents an external store (file) of persisted data. It’sthe object that actually maps between objects in your application and records in the database. There aredifferent classes of persistent object store for the different file types that Core Data supports. You can alsoimplement your own if you want to support a custom file type—see Atomic Store Programming Topics . Tolearn more about persistent stores and the different types, see “Persistent Store Features” inCore Data ProgrammingGuide .

In an iOS application, you generally just have a single store, but in complex applications (particularly forMac OS X) there may be several, each potentially containing different entities. The persistent store coordinator’srole is to manage these stores and present to its managed object contexts the façade of a single unified store.When you fetch records, Core Data retrieves results from all of them (unless you specify which store you’reinterested in).

In any application, you might have multiple managed object contexts. You might want to maintain discretesets of managed objects and edits to those objects; or you might want to perform a background operationusing one context while allowing the user to interact with objects in another. Each of these would be connectedto the same coordinator.



12

Figure 1-4 (page 13) illustrates the role the coordinator plays. Stacks aren’t usually this complicated.

Figure 1-4 A complex Core Data stack

Managed Object Context Managed Object Context

Persistent Object Store Persistent Object Store Persistent Object Store

Managed Object ModelPersistent Store CoordinatorA collection of

entity descriptions

DepartmentEmployee

Customer Contractor

DepartmentEmployee

Customer



13

The goal of this chapter is to create an initial implementation of the table view controller, and to update theapplication delegate to create and configure an instance of the table view controller.

This chapter sets up the table view, creating an instance of a navigation controller and a table view controller,and configuring the Core Location manager. This provides the architecture for the application. In the nextchapter, you’ll use Core Data to manage the actual data.

It’s assumed that you’re already familiar with view controllers and table views; this chapter does not providesignificant detail or explanation beyond that you need to understand the role of each of the components inthe application. If any of this is too challenging, you should stop here and practice writing some moreapplications before continuing.

The application delegate is responsible for creating, configuring, and displaying a navigation controller and atable view controller.

The table view controller displays the array of event objects. To support this, the controller adds four propertiesto the basic table view controller:

● A mutable array, which contains the collection of event objects that the table view controller displays.It’s populated from the application’s persistent store when the application starts up, and updated as theuser adds and removes events.

● A managed object context, which serves as your gateway to the Core Data stack.

● A Core Location manager, which provides location information to the application. The user can add newevents only when this is active (the Simulator simulates activity so you don’t need to install the applicationon a device to test it).

● A bar button item, which the user needs to add events. You need a reference to the button so you canconditionally enable and disable it in response to changes in the Core Location manager’s state.

Creating and Defining the RootViewController ClassFirst, create files for the new class.

>> In Xcode, create a new UITableViewController subclass; call it RootViewController. (Do not createa nib file.)


14

The Table View Controller

Next, add four properties, for the events array, the managed object context, the Core Location manager, andan Add button. The root view controller serves as the Core Location manager’s delegate, so it must adopt theCLLocationManagerDelegate protocol.

>> Replace the contents of the RootViewController header file with the following:

#import <CoreLocation/CoreLocation.h>

@interface RootViewController : UITableViewController <CLLocationManagerDelegate>{

NSMutableArray *eventsArray;

NSManagedObjectContext *managedObjectContext;

CLLocationManager *locationManager;

UIBarButtonItem *addButton;

}

@property (nonatomic, retain) NSMutableArray *eventsArray;

@property (nonatomic, retain) NSManagedObjectContext *managedObjectContext;

@property (nonatomic, retain) CLLocationManager *locationManager;

@property (nonatomic, retain) UIBarButtonItem *addButton;

@end

Implementing the RootViewController ClassThere are several parts to the initial implementation; you need to:

● Synthesize the properties you declared.

● Implement viewDidLoad to set up the Core Location manager and the Add and Edit buttons.

● Write the accessor method for the Core Location manager and implement two of its delegate methods.

● Implement methods to take care of memory management.

The Table View ControllerImplementing the RootViewController Class


15

All the code described in the following sections goes into the @implementation block of theRootViewController class, replacing implementations provided by the template as appropriate.(Implementations for the table view data source methods are described later.)

Synthesize the Properties>> Add these lines:

@synthesize eventsArray;

@synthesize managedObjectContext;

@synthesize addButton;

@synthesize locationManager;

Write the Accessor Method for the Core Location Manager>> Create an accessor method to dynamically create the Core Location manager on demand:

- (CLLocationManager *)locationManager {

if (locationManager != nil) {

return locationManager;

}

locationManager = [[CLLocationManager alloc] init];

locationManager.desiredAccuracy = kCLLocationAccuracyNearestTenMeters;

locationManager.delegate = self;

return locationManager;

}

Next, implement two delegate methods to enable and disable the Add button as appropriate. If the CoreLocation manager is generating updates, then enable the button; if the Core Location manager is failing, thendisable the button.

>> Add the following two Core Location manager delegate methods:

- (void)locationManager:(CLLocationManager *)manager



16

didUpdateToLocation:(CLLocation *)newLocation

fromLocation:(CLLocation *)oldLocation {

addButton.enabled = YES;

}

- (void)locationManager:(CLLocationManager *)manager

didFailWithError:(NSError *)error {

addButton.enabled = NO;

}

Implementing viewDidLoadThe viewDidLoad method needs to set up the Core Location manager and the Add and Edit buttons.

>> Replace the implementation of viewDidLoad with the following:

- (void)viewDidLoad {

[super viewDidLoad];

// Set the title.

self.title = @"Locations";

// Set up the buttons.

self.navigationItem.leftBarButtonItem = self.editButtonItem;

addButton = [[UIBarButtonItem alloc]initWithBarButtonSystemItem:UIBarButtonSystemItemAdd

target:self action:@selector(addEvent)];

addButton.enabled = NO;

self.navigationItem.rightBarButtonItem = addButton;

// Start the location manager.

[[self locationManager] startUpdatingLocation];

}



17

Implement Methods for Memory Management>> Replace the existing implementations of viewDidUnload and dealloc. The implementation ofviewDidUnload should relinquish ownership of anything created in viewDidLoad that can be recreated.

- (void)viewDidUnload {

self.eventsArray = nil;

self.locationManager = nil;

self.addButton = nil;

}

- (void)dealloc {

[managedObjectContext release];

[eventsArray release];

[locationManager release];

[addButton release];

[super dealloc];

}

Configuring the Application DelegateThe application delegate is responsible for creating and configuring the root view controller and a navigationcontroller to contain it.

Add the Navigation Controller PropertyYou need to add a property for the navigation controller.

>> In the application delegate’s header file (LocationsAppDelegate.h), add an instance variable:

UINavigationController *navigationController;

>> Add the property declaration:

@property (nonatomic, retain) UINavigationController *navigationController;

The Table View ControllerConfiguring the Application Delegate


18

Implement the Application DelegateIn the application delegate’s implementation file (LocationsAppDelegate.m), you need to:

● Import the RootViewController’s header file.

● Synthesize the navigationController property.

● In the applicationDidFinishLaunching:method, create an instance of RootViewController anda navigation controller to contain it.

You also need to pass the application’s managed object context to the new root view controller.

>> Before the @implementation block of the application delegate class, import the RootViewControllerclass’s header file:

#import "RootViewController.h"

>> In the @implementation block of the application delegate class, synthesize the navigation controllerproperty:

@synthesize navigationController;

>> Replace your application delegate’s application:didFinishLaunchingWithOptions: method withthe following implementation:

- (BOOL)application:(UIApplication *)applicationdidFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

RootViewController *rootViewController = [[RootViewController alloc]

initWithStyle:UITableViewStylePlain];

NSManagedObjectContext *context = [self managedObjectContext];

if (!context) {

// Handle the error.

}

// Pass the managed object context to the view controller.

rootViewController.managedObjectContext = context;

UINavigationController *aNavigationController = [[UINavigationController alloc]

The Table View ControllerConfiguring the Application Delegate


19

initWithRootViewController:rootViewController];

self.navigationController = aNavigationController;

[window addSubview:[navigationController view]];

[window makeKeyAndVisible];

[rootViewController release];

[aNavigationController release];

return YES;

}

Build and TestAt this stage you should build and run the project to make sure that it all works.

The Table View ControllerBuild and Test


20

Note: For the application to work correctly, you must not disable your computer’s location services(see Security > General in System Preferences). When it launches, you must also allow the applicationto use your location.

When it launches, the application should display a blank table view with a navigation bar. The navigation barshould contain the Edit and Add buttons:

The Add button will initially be disabled, but after a few seconds it should become enabled (as the locationmanager starts sending events). If you tap it, the application will of course crash since you haven’t yetimplemented the addEvent method. Before you can add an event, though, you need to define the Evententity. That’s what you’ll do next.

The Table View ControllerBuild and Test


21

The goal of this chapter is to allow users to create a new event when they tap the Add button. To do this, youneed to define the Event entity in the managed object model, implement the corresponding class, and createan instance of the class in the add method.

Modeling Your DataAs noted in “The Managed Object Model” (page 11), the model is a collection of entity and property descriptionobjects that tell Core Data about the managed objects in your application. You can create the modelprogrammatically, or use the Xcode modeling tool to create the model graphically, in a similar way to that inwhich you create a user interface using Interface Builder.

There are actually several ways to edit the constituent parts of the model; these steps typically describe justone. To learn more about the modeling tool, and other ways to edit the model, see Xcode Tools for Core Data .

This application has just a single entity, an Event, with three attributes—creation date, latitude, and longitude.

Add the EntityFirst, add an Event entity.

>> In Xcode, in the Resources group select the model file (Locations.xcdatamodel) to display the modeleditor.

>> Choose Design > Data Model > Add Entity to add a new entity to the model.

You can also use the Add button (+) at the lower left of the entity pane, or use the shortcut menu within thediagram view in the model editor.

You should see a new entry for the entity (called “Entity”) appear in the entity pane at the top left of thedocument editor, and a graphical representation of the entity (a rounded rectangle) appear in the diagramview. Now you can set the name for the new entity.

>> Make sure you have the new entity selected in the entity pane so that you see information about the entityin the detail pane at the right. Change the name of the entity to Event. (Don’t change the class name.)


22

Managed Object and Model

Your model should look similar to this:

There’s an important difference between the name of the entity and the name of the Objective-C class usedto represent instances of the entity. Core Data uses the entity description to find out about the data objectsit manages, so the class name doesn’t have to be the same as the entity name. Indeed, in some cases severalentities may be represented by the same class—NSManagedObject. Core Data is able to differentiate theinstances on the basis of their associated entity description.

Add the AttributesFirst, add the attribute for the creation date.

>> Make sure you have selected Event in the entity pane, then choose Design > Data Model > Add Attribute.

You should see a new attribute (called newAttribute) appear in the property pane. You need to set its nameand type.

>> Make sure you have selected the new attribute in the property pane, then in the detail pane change thename of the attribute to creationDate, and select Date from the Type pop-up menu.

Managed Object and ModelModeling Your Data


23

You don’t need to set any of the other values.

Now add attributes for latitude and longitude.

>> Make sure you have selected Event in the entity browser, then choose Design > Data Model > Add Attributetwice (to add two attributes).

>> Select both the new attributes in the property pane, then in the detail pane select Double from the Typepop-up menu.

>> Select just the first new attribute in the property pane, and in the detail pane change the Name of theattribute to latitude.

>> Select just the second new attribute in the property pane, and in the detail pane change the Name of theattribute to longitude.

Your model should look similar to this:

Managed Object and ModelModeling Your Data


24

Custom Managed Object ClassAlthough in principle you can represent an entity using NSManagedObject, in practice it is common to usea custom class. This yields several benefits, including:

● Better support from the development tools.

You get code completion for property accessor methods, and compile-time type- and symbol-checking.

● Support for custom methods for the entity.

In many situations, you want to provide special logic for the entity, such as validation methods or derivedproperties. For example, in a Person entity you might implement validation method to ensure that ahasDriversLicense property cannot be true if the age property is less than 17, or a fullName methodthat returns a suitable concatenation of firstName and lastName.

Now use Xcode to generate the files for a custom class to represent the Event entity.

>> In Xcode, in the model, select the Event entity . (You must select the entity; the selection is used to indicatewhich items to create subclasses for.)

>>Choose File > New File. In the New File dialog, select Managed Object Class.

Depending on the version of Xcode you’re using, the Managed Object Class may be available in the iOS sectionunder Cocoa Touch Classes, or you may need to choose the template in the Mac OS X section, underCocoa—either will work correctly.

>>Click Next. The correct location and targets should have been selected for you. Click Next to accept them.

You should see the Entity selection pane, with the Event entity selected. The “Generate accessors” and “GenerateObjective-C 2.0 properties” options should also be selected.

>>Click Finish to generate the files.

The Event class interface and implementation files are created and added to your project. There are a fewthings to notice:

● In the interface file (Event.h), all the attributes are represented by object values.

Although you specified the latitude and longitude attribute types as Double, the property values atruntime are instances of NSNumber. Core Data uses objects to represent values.

● In the implementation file (Event.m), the properties are implemented as dynamic.

Normally you might expect to see synthesized, however Core Data generates the accessor methods atruntime.

● In the implementation file (Event.m), there is no dealloc method.

Managed Object and ModelCustom Managed Object Class


25

Normally you might expect to see a dealloc method to release instance variables, however Core Datais responsible for the life-cycle of allmodeled properties of a managed object. (If you add your own instancevariables that do not have corresponding properties in the managed object model, then you need tomanage those yourself as normal.)

● The model is also updated—the Event entity is now represented by the Event class.

Because the model was changed, you need to save it.

>>Save the model file.

Finally, because the table view controller is going to make use of the new class, import its header file in thetable view controller’s implementation file.

>> In the table view controller’s implementation file (RootViewController.m), after the initial importstatement, add:

#import "Event.h"

Core Data RecapYou used the Xcode data modeling tool to create a new entity. You then created a custom class to representthat entity. In the next chapter, you’ll create instances of the entity.

If you want to learn more about the modeling tools, see Xcode Tools for Core Data .

Managed Object and ModelCore Data Recap


26

The goal of this chapter is to create the application logic to allow the user to create new event objects anddisplay them in the user interface.

Implementing the addEvent MethodYou create new Event objects in the addEvent method. Recall that it’s invoked when the user taps the Addbutton (see “Implementing viewDidLoad” (page 17)). There are several parts to the method. It has to:

● Get the current location

● Create an Event object and configure it using the current location information

● Save the Event object

● Update the events array and the user interface

First, though, declare the addEvent method.

>> Add a declaration of the addEvent method to the RootViewController header file:

- (void)addEvent;

Get the Current LocationWhen you create a new Event object, you need to set its location. You get the location from the locationmanager. If it’s not able to provide a location, then don’t continue.

>> Add the following to RootViewController implementation file:

- (void)addEvent {

CLLocation *location = [locationManager location];

if (!location) {

return;

}


27

Adding Events

}

Create and Configure the Event objectYou typically create a managed object using a conveniencemethod—insertNewObjectForEntityForName:inManagedObjectContext:—ofNSEntityDescription, which returns a properly initialized instance of the correct class for the entity youspecify, inserted into the managed object context. (For more about the initialization process, see “Managed Objects”

in Core Data Programming Guide ). After you’ve created the object, you can set its property values.

You get the latitude and longitude from the location as scalar values, so you need to convert these to NSNumberobjects for the Event object. You could get the time stamp from the location as well, but this is a constantvalue in Simulator. Instead, here you can use date method of NSDate to get a date object representing thecurrent date and time.

>> Add the following code at the end of the current implementation of addEvent:

// Create and configure a new instance of the Event entity.

Event *event = (Event *)[NSEntityDescription insertNewObjectForEntityForName:@"Event"inManagedObjectContext:managedObjectContext];

CLLocationCoordinate2D coordinate = [location coordinate];

[event setLatitude:[NSNumber numberWithDouble:coordinate.latitude]];

[event setLongitude:[NSNumber numberWithDouble:coordinate.longitude]];

[event setCreationDate:[NSDate date]];

This illustrates the general technique you use to update a managed object, whether it’s a new managed objectyou created, or one you fetch from the store. You simply use accessor methods, just as you would any otherCocoa object. Importantly, though, changes are not pushed to the persistent store until you explicitly save thecontext.

Save the New EventRemember that the managed object context acts like a scratch pad (see “Managed Objects and the ManagedObject Context” (page 10)). Whatever changes you make—whether editing property values or adding ordeleting whole objects—aren’t actually committed to the persistent store (file) until you save the context.Typically, in an iOS application, you save changes as soon as the user has made them.


Adding EventsImplementing the addEvent Method


28

NSError *error = nil;

if (![managedObjectContext save:&error]) {


}

In common with several Core Data methods, the NSManagedObjectContext save: method takes an errorparameter and returns a Boolean value to indicate success or failure. The situation is really no different fromthat in any other application; it’s just that the return value from the save: method and the error parametertend to bring into sharper focus the possibility of a problem occurring.

Handling ErrorsIt’s up to you to decide how you handle a Core Data error.

In a scenario as simple as that described in “Save the New Event” (page 28)—where the only change youexpect is the addition of a single object—if the data can’t be saved it’s likely to be indicative of some sort ofcatastrophic failure from which recovery might be difficult or impossible. In this situation you might just presentan alert sheet telling the user to restart the application.

In a more complex scenario, the user might have changed property values, or added or deleted managedobjects in such a way that either an individual object is in an inconsistent state (validation fails) or the objectgraph as a whole is inconsistent. If you have more than one managed object context, it’s also possible that thepersistent store was updated when changes made in a different context were committed and so the objectsin the current context are inconsistent with the corresponding records in the store.

In general, you can interrogate the error object to find out what went wrong.

You should think carefully about what the user experience should be in the event of an error occurring. Whatinformation should you present to the user? What options might you give them for recovering from theproblem? These are not questions that Core Data is able to answer.

Update the Events Array and the Table ViewFinally, you need to add the new Event object to the events array, then update the table view. Since this is anew Event, and Events are displayed with most recent events at the top of the list, add the new object to thebeginning of the events array, add a corresponding row to the top of the table view, then scroll the table viewto show the new row.


[eventsArray insertObject:event atIndex:0];

Adding EventsImplementing the addEvent Method


29

NSIndexPath *indexPath = [NSIndexPath indexPathForRow:0 inSection:0];

[self.tableView insertRowsAtIndexPaths:[NSArray arrayWithObject:indexPath]

withRowAnimation:UITableViewRowAnimationFade];

[self.tableView scrollToRowAtIndexPath:[NSIndexPath indexPathForRow:0 inSection:0]atScrollPosition:UITableViewScrollPositionTop animated:YES];

The next task is to complete the implementation of the table view data-source methods to display the events.

Displaying Events in the Table ViewYou need to update two table view data-source methods to display the events.

First simply tell the table view how many events to display.

>> Update the implementation of tableView:numberOfRowsInSection: to return the number of objectsin the events array (there’s only one section, so you don’t need to test the section number):

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

return [eventsArray count];

}

Next, you need to configure the table view cells to display information about each event. You’ll see there is anontrivial amount of code, but most of it is related to user interface and display rather than data management.

>> Replace the implementation oftableView:(UITableView *)tableView cellForRowAtIndexPath:with the following:

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

// A date formatter for the time stamp.

static NSDateFormatter *dateFormatter = nil;

if (dateFormatter == nil) {

dateFormatter = [[NSDateFormatter alloc] init];

[dateFormatter setTimeStyle:NSDateFormatterMediumStyle];

[dateFormatter setDateStyle:NSDateFormatterMediumStyle];

Adding EventsDisplaying Events in the Table View


30

}

// A number formatter for the latitude and longitude.

static NSNumberFormatter *numberFormatter = nil;

if (numberFormatter == nil) {

numberFormatter = [[NSNumberFormatter alloc] init];

[numberFormatter setNumberStyle:NSNumberFormatterDecimalStyle];

[numberFormatter setMaximumFractionDigits:3];

}

static NSString *CellIdentifier = @"Cell";

// Dequeue or create a new cell.

UITableViewCell *cell = [tableViewdequeueReusableCellWithIdentifier:CellIdentifier];

if (cell == nil) {

cell = [[[UITableViewCell alloc] initWithStyle:UITableViewCellStyleSubtitlereuseIdentifier:CellIdentifier] autorelease];

}

Event *event = (Event *)[eventsArray objectAtIndex:indexPath.row];

cell.textLabel.text = [dateFormatter stringFromDate:[event creationDate]];

NSString *string = [NSString stringWithFormat:@"%@, %@",

[numberFormatter stringFromNumber:[event latitude]],

[numberFormatter stringFromNumber:[event longitude]]];

cell.detailTextLabel.text = string;

return cell;

}

Adding EventsDisplaying Events in the Table View


31

Build and TestIf you build the project, it should compile without errors. The application should also launch and run correctly,until you tap the Add button—at which point it will crash. This is because the events array hasn’t been createdyet.

>> Solely for testing purposes , add the following line to the end of the RootViewController object’simplementation of viewDidLoad:

eventsArray = [[NSMutableArray alloc] init];

If you build and run now, you should find that if you tap the Add button new events are displayed in the tableview. If you quit and relaunch the application, though, you won’t see the list of Events when it starts up. Toremedy this, you need to populate the events array on launch with the existing Event objects. This is yourtask in the next chapter. Before doing that, restore the project to its pre-testing state.

>> Delete the line you added for testing.

Core Data RecapThere was a lot of code in this chapter, and not much related directly to Core Data. The important points arethat:

● You typically create a new managed object using the convenience methodinsertNewObjectForEntityForName:inManagedObjectContext: of NSEntityDescription.

This method ensures that you get a properly initialized instance of the class that represents the entity youspecify.

● To commit changes to the persistent store, you need to save the managed object context.

The context acts as a scratch pad; if you add or modify objects, the changes are held in memory until youinvoke save:. It’s up to you to decide how to deal with any error that might occur during a save operation.

● You get and set a managed object’s property values using accessor methods, just as you would any otherobject.

You can also use key-value coding, just as you would any other object, but using accessor methods ismuch more efficient (see “Using Managed Objects” in Core Data Programming Guide ).

Adding EventsBuild and Test


32

The goal of this chapter is to fetch existing Event objects when the application launches.

Fetching Managed ObjectsTo fetch objects from a persistent store, you need a managed object context and a fetch request. A fetchrequest is an instance of NSFetchRequest. As a minimum, it specifies the entity you’re interested in. It mayalso specify any constraints on the values that the objects should have and what order you want them backin. For example, in a corporate information application, you might create a fetch request to retrieve Employeeobjects, ordered by name, whose salary is greater than a certain amount. The constraints are represented bya predicate—an instance of NSPredicate. (For more about predicates see Predicate Programming Guide .)The sort order is represented by an array of NSSortOrdering objects.


Execute fetch request

Response

Query

Returns

Persistent Store Coordinator

Array

Persistent Object Store

Entity (table name)

Predicate (optional)

Sort orderings (optional)

Employee

salary > 60000

name: ascending alphabetical

Fetch Request


Fred97000


Juli90000


33

Fetching Events

Unless you really need all the objects of a particular entity, you should use a predicate to limit the number ofobjects returned to those you’re actually interested in. (If you’re displaying objects in a table view, you canalso use a fetched results controller—NSFetchedResultsController—to manage a result set for you. Itworks hard to ensure that as little data as possible is held in memory.)

Note that you don’t always need to execute a fetch to retrieve objects. Core Data, if necessary, automaticallyretrieves objects that are at the destination of a relationship. For example, if you execute a fetch to retrieve anEmployee object, then ask it for its related Department, then Core Data fetches the Department for you ifit hadn’t already been fetched.

Creating and Executing the RequestWhen the table view controller loads its view, it should fetch the Event objects and keep them in the eventsarray so that they can be displayed later. The events array needs to be mutable since the user can add andremove events.

Create the RequestCreate a fetch request and set the entity.

>> Add the following code at the end of the current implementation of viewDidLoad:

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

NSEntityDescription *entity = [NSEntityDescription entityForName:@"Event"inManagedObjectContext:managedObjectContext];

[request setEntity:entity];

The method of interest here is NSEntityDescription’s entityForName:inManagedObjectContext:.You provide the name of the entity you want and the managed object context you’re dealing with; the methodthen asks for the (managed object) context’s (persistent store) coordinator’s (managed object) model andretrieves from that the entity with the name you specified (you can refer back to “The Core Data Stack” (page9) to see a pictorial representation). Conceptually it’s not very difficult (you just navigate down the stack),and you could do it yourself easily enough, but it’s much more convenient to use the class method.

Fetching EventsCreating and Executing the Request


34

Set the Sort DescriptorIf you don’t specify a sort descriptor, the order in which objects are returned from a fetch is undefined. Toretrieve the Events in chronological order, you therefore need to specify a sort descriptor for the fetch. Becauseyou might want to specify multiple sort orderings (for example, you might want to sort employees bydepartment, last name, and first name), you need to put the sort descriptor in an array.

>> At the end of the current implementation of viewDidLoad, create a sort descriptor to order Event objectsby creation date—most recent first—and a mutable array. Add the sort descriptor to the array, and set thearray as the fetch request’s sortDescriptors array:

NSSortDescriptor *sortDescriptor = [[NSSortDescriptor alloc]initWithKey:@"creationDate" ascending:NO];

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

[request setSortDescriptors:sortDescriptors];

[sortDescriptors release];

[sortDescriptor release];

(It’s often useful to use the initWithObjects: method of NSArray in case you want to add more sortdescriptors later.)

Execute the RequestHaving created a fetch request, you now execute it. The events array needs to be mutable, so make a mutablecopy of the result.



NSMutableArray *mutableFetchResults = [[managedObjectContextexecuteFetchRequest:request error:&error] mutableCopy];

if (mutableFetchResults == nil) {


}

As previously, this example leaves it up to you to decide how to handle any error (see “Handling Errors” (page29)).

Fetching EventsCreating and Executing the Request


35

Finish UpThe final steps are to set the view controller’s events array instance variable and to release objects that wereallocated.


[self setEventsArray:mutableFetchResults];

[mutableFetchResults release];

[request release];

Build and TestIf you build and run the application, you should find that it compiles correctly and that existing Event objectsare displayed when the application launches.

Core Data RecapThe important points from this chapter are that:

● You fetch managed objects by creating a fetch request.

As a minimum, you need to specify an entity. You get the entity using the convenience methodentityForName:inManagedObjectContext: of NSEntityDescription. You might also specify apredicate and an array of sort orderings.

To ensure that you retrieve no more objects than necessary (and so keep memory usage down), you shouldtypically try to constrain your request as narrowly as possible using a predicate.

● You don’t always need to explicitly fetch managed objects.

This wasn’t addressed directly in code, since there are no relationships in this tutorial. To repeat the pointmade earlier, though: Core Data, if necessary, automatically retrieves objects that are at the destinationof a relationship. For example, if you execute a fetch to retrieve an Employee object, then ask it for itsrelated Department, Core Data fetches the Department for you if it hasn’t already been fetched.

Fetching EventsBuild and Test


36

The goal of this chapter is to allow the user to delete events from the list.

Deleting Managed ObjectsAs you saw when you created a new managed object, the lifetime of a record in the database is not tied tothe lifetime of a given managed object. If you create a managed object, it doesn’t mean a record automaticallyis created for that object in the database—you need to save the context. Similarly, simply because an objectis deallocated does not mean that the corresponding record itself is destroyed.

To delete a record, you tell the managed object context to mark an object as deleted, using the deleteObject:method of NSManagedObjectContext. Then to actually destroy the record, you commit the action usingsave:.

Deleting an EventTo handle deletion, you implement the table view data source methodtableView:commitEditingStyle:forRowAtIndexPath:. It needs to do three things:

1. Delete the selected object.

2. Update the table view.

3. Save the changes.

It should do this only if the action is a delete.

>> In the RootViewController implementation file, implement thetableView:commitEditingStyle:forRowAtIndexPath: method as follows:

- (void)tableView:(UITableView *)tableViewcommitEditingStyle:(UITableViewCellEditingStyle)editingStyleforRowAtIndexPath:(NSIndexPath *)indexPath {

if (editingStyle == UITableViewCellEditingStyleDelete) {


37

Deleting Events

// Delete the managed object at the given index path.

NSManagedObject *eventToDelete = [eventsArray objectAtIndex:indexPath.row];

[managedObjectContext deleteObject:eventToDelete];

// Update the array and table view.

[eventsArray removeObjectAtIndex:indexPath.row];

[tableView deleteRowsAtIndexPaths:[NSArray arrayWithObject:indexPath]withRowAnimation:YES];

// Commit the change.


if (![managedObjectContext save:&error]) {


}

}

}

Build and TestBuild and test the application. You should find that it compiles and runs without error. If you tap Edit, the tableview should enter edit mode. If you delete a row, it should be properly deleted from the table view. If you quitand relaunch the application, the row you deleted should no longer be visible.

You’ve now completed the tutorial. You can start investigating ways to enhance your knowledge andunderstanding of Core Data. Some suggestions are given in the next chapter.

Core Data RecapYou’ve now performed the basic tasks you need to be familiar with to use Core Data—you:

● Created an entity in a managed object model. You also created a custom class to represent the entity.

● Created an instance of a managed object. You also changed some of its property values.

● Fetched managed objects.

● Deleted a managed object.

Deleting EventsBuild and Test


38

You may have noticed that, in performing these tasks, the only object in the Core Data stack (see “The CoreData Stack” (page 9)) with which you interacted directly was the managed object context. Although youhave access to the other objects in the stack, you often don’t need to use them directly. Either the Xcodetemplate takes care of setting them up, or you use a convenience class method to accomplish a particular taskthat would otherwise require you to access them.

Deleting EventsCore Data Recap


39

Here are some suggestions for ways in which you can enhance your understanding of Core Data and how youcan integrate it in your applications. As you explore, you can turn to the Core Data Programming Guide forhelp.

Changing the Model Means you Cannot Open Existing Stores: If you change the schema in yourmanaged object model, your application typically won’t be able to open files you created with anearlier version. This is an issue that you might address as your experience grows (see Core DataModelVersioning and Data Migration Programming Guide ). First, though, there are some easier steps totake.

The Core Data Utility TutorialIt’s worth turning away from iOS for a short while and working through Core Data Utility Tutorial . It’s similarin many respects to this tutorial, but it’s freed from the distraction of a user interface. It introduces a couple ofnew concepts regarding the lifecycle of a managed object, and reinforces the idea of the managed objectmodel being just a collection of objects—by having you create one programatically.

Use a Fetched Results ControllerTurning back to iOS, try to update the Locations application to use an NSFetchedResultsController object.A fetched results controller is intended primarily to make fetching large numbers of objects much more efficient,but it’s worth practicing using one with a smaller data set. For comparison, look at the CoreDataBooks example.

Creating a Managed Object Model with XcodeRead Xcode Mapping Tool for Core Data . You will learn more about the Xcode tools for Core Data, and inparticular how to establish relationships between entities. This will be essential if you want to create applicationsthat contain entities that are related to each other, as suggested in “A Drill-Down Interface” (page 41).


40

Next Steps

A Drill-Down InterfaceExtend the Locations application to provide a drill-down interface to allow users to inspect an event—perhapsto edit comments or a add photograph. You need to add more properties to the Event entity, and perhaps asecond entity. The TaggedLocations sample provides an example of using a second entity with a to-manyrelationship.

If you add a photograph, consider the memory management implications of fetching a photograph with everyEvent you retrieve from the store. Core Data has a feature called faulting (see “Managed Objects” in Core DataProgramming Guide ) which means that it doesn’t have to complete the object graph. You would typicallymodel the photograph as a separate entity, with a relationship from the Event entity to the Photo entity (anda reciprocal relationship from the photo to the event). When you retrieve just a single Event object, the photorelationship may be represented by a fault. If you ask an event for its photo, Core Data automatically fulfillsthe fault and retrieves the corresponding data for you. See PhotoLocations for an example.

Add an Add SheetAn Add sheet allows you to enter more information about an event when you create it. Think about whatinformation you might pass to the Add sheet controller. Think also about how you might keep the edits madeto the Event object in the Add sheet discrete from edits made in the rest of the application. (Hint: you mightconsider using two managed object contexts—see the CoreDataBooks example.)

Next StepsA Drill-Down Interface


41

This table describes the changes to Core Data Tutorial for iOS .

NotesDate

Made minor editorial corrections thoughout. Fixed broken links.2012-12-13

Updated for iOS 4.0 and later.2010-11-15

Changed the title from "Core Data Tutorial for iPhone OS."2010-07-08

Corrected links to sample applications.2009-09-09

Corrected typographical errors.2009-06-04

Added a missing line of code to the implementation ofapplicationDidFinishLaunching:.

2009-03-19

First version of a tutorial that introduces application development foriPhone using Core Data.

2009-03-15


42

Document Revision History

Apple Inc.© 2012 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, Cocoa, Cocoa Touch,iPhone, Mac, Objective-C, and Xcode aretrademarks of Apple Inc., registered in the U.S.and other countries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

iphone programming: core data tutorial for ios

Technology

core data tutorial

core data recap

core data utility tutorial

simple core data stack

complex core data stack

model objects

managed object model

data store versioning