Introduction to Core Data, Part II
Volume Number: 21 (2005)
Issue Number: 9
Column Tag: Programming
Introduction to Core Data, Part II
Diving More Deeply into Apple's New Persistence Framework
by Jeff LaMarche
In the first part of this article we built a simple, but relatively complete application for
keeping track of a collection of books. We wrote very little code to create that application, and
leveraged an amazing amount of Core Data's "for free" functionality. There will inevitably be times,
as you write Core Data applications, however, where you need to be able to create, change, and
delete data programmatically and there will also certainly be times when you need to do things in
your application that Core Data simply doesn't do for you.
You might, for example, need to do conditional validation of a field, or provide a default value
for a new instance based on other data in your application. In this month's article, we are going
to combine the simple book-tracking application from the first Core Data article with our code from
the NSXML article that ran in the June issue to create an application that will both track
information about books, as well as look up book information based on ISBN using Amazon's web
In order to implement this functionality, we're going to need to be able to create new entity
instances and populate the attributes of those instances programmatically. We're also going to need
to subclass NSManagedObject to implement validation and defaulting behavior that is too complex to
be accommodated by using only the various fields of the data modeler.
We'll be using our project from the first part of this article (which ran in the July issue) as
our starting point for this month. Also, If you haven't already read it, you may want to review the
article on NSXML from the June issue, since I will be using, but not explaining, some code we wrote
in that article. You can download the project from the first part of this article at ftp://ftp.mactech.com/src/mactech/volume21_200521.07.sit and use that as a starting point if you wish. You'll also need the two categories from the
NSXML project in order to compile some code in this month's article, so you'll probably want to grab
it at ftp://ftp.mactech.com/src/mactech/volume21_2005/21.06.sit if
you plan on trying out this month's code.
Start Me Up
Open up the MTCoreData project from last month in Xcode. Single click on
MTCoreData_DataModel.xcdatamodel so that the data model editor is showing. If the editor doesn't
show up when you single-click the data model icon, select Zoom Editor In from the View menu, or
press the Editor button on Xcode's toolbar.
Single-click on the Book entity in the Entity pane (the top left pane in the data model editor).
Once you do that, a list of the book's attributes should appear in the top middle pane. There are
two attributes to which I want to draw your attention. These attributes are dateRead and url. Now,
wouldn't it be nice if we could default the dateRead field to the date on which the book was entered
into the database, or find a way to validate that url is actually a valid internet URL? There's no
way to do either of these things using just the entity or attribute inspectors available in the data
modeler, but they can be done. In fact, we're going to do both of those things in this article.
If you look in the top right-most pane of the editor, you'll notice that the Book entity
currently has specified a class of NSManagedObject. Go ahead and change that to MTBookEntity. What
we've just done is specified a different class to represent the Book entity. At the moment, the
class we specified doesn't exist, but we're going to create it.
Figure 1. Creating the
files for MTBookEntity
Since NSManagedObject already does most of what we need done, our new class is going to be a
subclass of it. Press ?N or select New File... from the File Menu. Select Objective-C Class from the
New File Assistant and name the new file MTBookEntity.m. Before hitting return, make sure that Also
Create "MTBookEntity.h" is selected (figure 1). After you hit return, you'll have two new files in
your project. Single-click first on MTBookEntity.h, so that we can change the superclass from
NSObject to NSManagedObject. This is absolutely necessary; although the modeler will let you specify
any class, at runtime your application is only going to work if the class you specified responds to
all the methods that NSManagedObject responds to.
The only change at this point is to make NSManagedObject rather than NSObject the superclass.
@interface MTBookEntity : NSManagedObject
Implementing Custom Default Behavior
You'll notice that we haven't added any new methods or instance variables at this point.
NSManagedObject already provides us with a mechanism for validating and defaulting values, as well
as methods to allow getting and setting attributes using Key Value Coding or KVC.
Switch now to MTBookEntity.m so we can implement the defaulting behavior for the dateRead
attribute. There is a method in NSManagedObject that is specifically designed to be overridden by
subclasses in order to set default attribute values. That method is called awakeFromInsert. To set
the default value of dateRead to the current date, all we have to do is override awakeFromInsert,
and set the attribute using key value coding, like so:
This method is called when an entity instance is first created. It is where
customized default values for attributes should be set.
- (void) awakeFromInsert
[self setValue:[NSCalendarDate date] forKey:@"dateRead"];
Yep, that's all there is to it. We don't even need to call [super awakeFromInsert]; we just
implement the method if we need it and do any custom defaulting that we need to do. Notice that we
didn't use a mutator to set the value, but rather used setValue:forKey: and passed in the name of
the attribute we're setting as the key value.
Custom Attribute Validation
As you just saw, adding custom defaulting to a custom managed object couldn't be easier. Custom
validation is not quite as straightforward. The obvious and, unfortunately, wrong way to do it would
be to subclass NSManagedObject's validateValue:forKey:error: and implement your validation there.
Apple strongly suggests that developers implement custom validation methods and leave
validateValue:forKey:error: alone. Your custom methods will be called instead of
validateValue:forKey:error: if your method name conforms to the naming convention
validate:error:, where is replaced with the name of the attribute for which you wish to
implement validation (i.e. validateFoo:Error:). Implementing the method is relatively simple; you
just return YES if the value is okay to be saved, and NO if it isn't. If you return NO, you should
also allocate an NSError with more detailed information about why validation failed. Let's create a
custom validation method for url, shall we?
Custom validation methods (and, as we'll see later, custom accessors and mutators) must be
declared in your subclass' header file because they do not exist in the superclass
(NSManagedObject). Therefore, we have to add a method declaration to MTBookEntity.h:
Add this declaration just before @end
After creating the method declaration, we need to switch to the implementation file and write the
actual validation. There is a bit of a gotcha here. See those double astericks (**) on the method's
parameters? That's not a typo; both parameters for custom validation methods are passed as pointers
to pointers (sometimes called a handle), so you have to de-reference them before trying to access
them as Objective-C objects.
// Create a local de-referenced variable to make code more readable
// You can skip this and just use *urlstring anywhere I use val
// if you prefer not to allocate a stack variable unnecessarily
NSString *val = *urlString;
// Not a required attribute, so bail without validating if empty or nil
if (val == nil || [val length] == 0)
// Create an NSURL. If unable to instantiate, populate error and return NO
NSURL *url = [NSURL URLWithString:val];
if (url == nil)
// If we create a dictionary containing a string using one of the
// following keys:
// that message will be displayed when validation failed.
// Otherwise, it will use the error code and error domain
// to determine what to display to the user. Since we don't
// have an error code that corresponds to our error, we'll
// do it this way and pass a generic -1 error code
NSDictionary *userInfoDict = [NSDictionary
dictionaryWithObject:@"Not a valid URL"
// There are a number of error domains that correspond to
// where the error was originally generated. Most of the
// time you'll use the first
*error = [[[NSError alloc] initWithDomain:
NSCocoaErrorDomain code:-1 userInfo:userInfoDict]
Other than the fact that we're being passed a handle rather than a pointer to an Objective-C
object, this is a fairly straight forward chunk of code. We return YES if the value can be turned
into an NSURL, NO if it can't. If the URL doesn't validate, we allocate an NSError and populate it
with an error domain, an error code, and a dictionary containing a string that explains why
Please note that you should avoid making changes to the object being passed in for validation.
Since you're given a handle to it, you actually can change the actual object that's stored in Core
Data's object graph, but doing so could potentially cause data consistency problems. Although it
does seems like they wouldn't pass you the data in this manner unless they expected you to sometimes
change it, Apple's documentation is very clear in stating that you should not. So don't, okay?
When Core Data goes to validate an attribute, it will first look for a custom validation method
like the one we just created. If such a method exists, it gets called. If no such method exists,
Core Data will then call the generic validateValue:forKey:error:. In that situation, we let our
superclass handle the validation.
Custom Accessors & Mutators
Before we dive into creating, modifying, and deleting objects programmatically, let's look at
implementing custom accessors and mutators (the methods used to get and set the value of instance
variables) for our subclass. Now, this is a purely optional step: You never need to implement
accessors or mutators for subclasses of NSManagedObject. The standard way of accessing attributes of
an entity is to use Key Value Coding, like so:
name = [entity valueForKey:@"name"];
This method of getting data from an entity works perfectly well, regardless of whether you are
using NSManagedObject or a custom subclasss. When you do subclass NSManagedObject, however, you have
the option of implementing custom accessors and mutators so that your subclass can be use in a more
intuitive fashion, like this:
name = [entity name];
Doing this generally makes for code that's a touch shorter, and which most people find to be a
bit more readable. The tradeoff, of course, is that you have to actually do the work to implement
these custom methods. Now choosing to implement them is not an all-or-nothing proposition. If you
want to implement accessors and mutators just for the attributes you use most often rather than for
all of the entity's attributes, that's perfectly acceptable. In the interest of space, we'll
implement accessors and mutators for just one attribute - title - to show how it's done.
Just as with custom validation methods, you should declare custom accessors and mutators in your
Add the following declarations before the @end directive
To implement these methods, we use NSManagedObject's key-kalue methods to get and set the
attribute values, but there's a little more to it than that because we have to let Core Data know
that we are accessing data that it manages. Core Data is very savvy about keeping its data context
consistent even when it's being accessed from different places in your application, but we have to
help it do its job right by telling it when we're going to start, and then again when we're done
accessing an attribute.
Outside of your NSManagedObject subclass, it is generally not necessary or even advisable to do
this, but you must do it here because we are directly accessing the data primitives. To implement
these methods correctly, we have to access and set the primitive values using primitiveValueForKey:
and setPrimitiveValue:forKey:. These two methods function identically to the standard valueForKey:
and setValue:forKey: methods with which you are probably already familiar, but these two must be
used when creating custom accessors and mutators, and no place else. Here are our implemented custom
- (NSString *)title
id title = [self primitiveValueForKey:@"title"];
- (void)setTitle:(NSString *)newTitle
[self setPrimitiveValue:newTitle forKey:@"title"];
At this point, you should be able to run the application, and it will work exactly as before,
except that the dateRead field will default to today's date, and only valid URLs will be accepted in
the url field.
Another handy thing that you can do when subclassing NSManagedObject is to create virtual
accessors. A virtual accessor is a method that functions just like an accessor, meaning you can bind
interface elements to it in Interface Builder. What's being accessed is not an actual entity,
however. Typically, you would do this with data calculated from actual attributes.
In our case, let's say we wanted to display the title of our books in the left-hand column just
as we do now, but we wanted to include the year the book was released in parenthesis after the
title. We don't want to add a column to the table, but just show it as a single column as it is now.
Obviously, we want to keep these two data fields separate in the data context. This is an ideal
place for a virtual accessor. Go ahead and declare a new accessor method called displayTitle: that
returns an NSString.
Add this declaration before the @end directive
Now implement this method just as we would a "real" accessor.
NSString *displayTitle = nil;
NSString *title = [self primitiveValueForKey:@"title"];
NSDate *dateReleased = [self
displayTitle = [NSString stringWithFormat:@"%@ (%@)",
return (displayTitle == nil) ? title : displayTitle;
Since we're accessing multiple attributes, we have to tell Core Data about every attribute that
we're using, and then again tell it when we're done with them. If there is no dateReleased field, we
return just the title by itself, otherwise return the title followed by the year from the date in
Okay, now that we have our very own virtual accessor, what do we do with it? Well, fire up
Interface Builder by double-clicking MainMenu.nib, and I'll show you. Once Interface Builder is
launched, double-click on the table on the left hand side of your application's main window--the one
that displays the list of books--and then single-click the column header. Press ?4 to bring up the
bindings inspector, and expand the value binding. The current Model Key Path, you'll see, is set to
title. Change that to read displayTitle, which will point it to our virtual accessor, and then save.
You can go ahead back to Xcode now and run the program if you want. You'll see that instead of
just the titles in the left hand column, there will now be the titles followed by the year the book
was published in parenthesis. Since the interface and data storage in Core Data applications are
totally independent of one another, the table column doesn't know and doesn't care that displayTitle
is not a real attribute.
Creating and Editing Core Data Entities
You may recall that we put a button on the interface last month, but didn't put any code behind
that button. Well, it's now time for the main event; let's put some code behind it. The first thing
we need to do is to declare a new IBOutlet method so that we have something to which we can bind the
Add a new method declaration to the existing application delegate header.
And, of course, we need to implement this new method. The comments explain what's going on.
Here is the implementation of our new action method. This method retrieves the
information about a book from Amazon based on the entered ISBN value, creates a new
MTBookEntity instance, and then sets the various fields from the retrieved data.
// Grab the currently selected item in the left-hand table
// - the one that's currently displayed
MTBookEntity *book = [[books selectedObjects]
// Retrieve the ISBN number typed in by the user
NSString *isbn = [[book valueForKey:@"isbn"]
// Use the ISBN the user typed in to create an Amazon URL
NSString *urlBase = @"http://xml.amazon.com/onca/xml3?t=
NSString *urlString = [NSString stringWithFormat:urlBase,
NSURL *theURL = [NSURL URLWithString:urlString];
// Initialize our document with the XML data in our URL
NSXMLDocument *xmlDoc = [[NSXMLDocument alloc]
initWithContentsOfURL:theURL options:nil error:&err];
// Get a reference to the root node
NSXMLNode *rootNode = [xmlDoc rootElement];
// In case of an error, Amazon includes a node called "ErrorMsg", its
// presence tells us that an error happened, so we check for it
NSXMLNode *errorNode = [rootNode childNamed:@"ErrorMsg"];
if (rootNode == nil || errorNode != nil)
// Nothing retrieved or error, throw up alert
NSRunAlertPanel(@"Error",@"Error retrieving XML data
about this book. Are you sure that's a valid
ISBN and you're connected to the
// Grab the details node
NSXMLElement *detailsNode = [rootNode
// Here's how we set a value using a custom mutator
NSString *bookTitle = [[detailsNode childNamed:
// Setting value using KVC
NSString *publisher = [[detailsNode childNamed:
[book setValue:publisher forKey:@"publisher"];
[book setValue:[[detailsNode childNamed:@"Asin"]
// We have to convert this number which is stored as a
// string into an NSNumber before setting value. Core
// Data number fields will not accept NSStrings even
// if they contain a valid number
NSNumber *rank = [NSNumber numberWithInt:[[[detailsNode
childNamed:@"SalesRank"] stringValue] intValue]];
[book setValue:rank forKey:@"salesRank"];
[book setValue:[[detailsNode attributeForName:@"url"]
// Get an enumerator that contains all the authors
// listed in the XML
NSXMLNode *authorsNode = [detailsNode
NSEnumerator *e = [[authorsNode childrenAsStrings]
// Get the Mutable Set that corresponds to the authors
// relationship - this will allow us to add Author entities
// to this Book entity
NSMutableSet *authorSet = [book mutableSetValueForKey:
// Loop through retrieved authors enumerator
while (oneAuthor = [e nextObject])
// Create and insert a new Author entity for each author found
NSManagedObject *author = [NSEntityDescription
// Set the author's name attribute
[author setValue:oneAuthor forKey:@"name"];
// Add the new author to the Book entity's authors relationship
// Note: Core Data automatically populates the Inverse relationship
// Get the image data from URL then store it
NSURL *imageURL = [NSURL URLWithString:[[detailsNode
[book setValue:[NSData dataWithContentsOfURL:imageURL]
That listing may look a little daunting, but don't be scared off by it; Core Data entities are
actually very easy to work with. You use valueForKey: and setValue:forKey: to get and set the values
for any given instance or, if you choose to implement them, you can call custom accessors and
mutators instead. To add an existing entity to the relationship of another entity, you use
mutableSetValueForKey: to retrieve the NSMutableSet that represents that relationship. Then when you
add or delete items from the returned NSMutableSet instance, what you are actually doing is adding
or deleting them from the entity's relationship.
Creating new objects, as you saw, is done by calling one of NSEntityDescription's class methods
called insertNewObjectForEntityForName:inManagedObjectContext:, supply the name of the type of
entity you want to create along with the context in which you want it created, and it will create
the instance and return a reference to it.
Now that we have our code in place, go to Interface Builder and make sure that the Lookup
button's target outlet is bound to the doLookup: method, and then go try it out.
One useful task that we didn't undertake in the code above was deleting an Entity. In our
application, the only place where we need to delete entities is really better handled as it
currently is: by using NSArrayController's remove: outlet. Just for grins and giggles, let's take a
quick look at how we would delete a book programmatically if we needed to. This is really, insanely
hard, so if you don't grasp it at first, it's okay. Just take a few deep breaths and re-read the
code sample a few times until it makes sense. I'm confident you can grasp it if you try hard enough.
Deleting a Core Data Entity
[[self managedObjectContext] deleteObject:book];
Still with me? Are you sure? Great!
Figure 2. The final
application in action.
This is the End
That's all there is for this month. We looked at subclassing NSManagedObject in order to
implement conditional defaulting and validation for our entity. We also took a look at how we
create, edit, and delete managed objects programmatically. Core Data is really an amazing technology
and a huge productivity booster for Mac application developers; these two articles have only
scratched the surface of what it can do for you. They should, however, have you enough of a
foundation to get in there and start making Core Data applications that really dance the Fandango.
Now, what are you waiting for? Go to it!
Jeff LaMarche wrote his first line of code in Applesoft Basic on a Bell & Howell Apple
//e in 1980 and he's owned at least one Apple computer at all times since. Though he currently makes
his living consulting in the Mac-unfriendly world of "Enterprise" software, his Macs remain his
first and greatest computer love. You can reach him at firstname.lastname@example.org.