The next thing you need to do is add the attributes to the entity. These correspond to the instance variables you are used to using, which correspond to the model's data.

Figure 4-5. The name of your entity is Hotel.

You start by adding the Name attribute.

Figure 4-6. Add an attribute.

Figure 4-7. Setting the name.

Figure 4-8. Setting the type.

When you're done, your model should look just like mine, as shown in Figure 4-9.

Now add attributes for city, state, street, and zip code by going through Steps 1–3 for each.

When you're done, your model should look like Figure 4-10.

Figure 4-9. The Hotel entity and with a name attribute.

Figure 4-10. An (almost) complete Hotel entity.

As I mention earlier, you need another entity as well — Annotation.

At this point, you may be saying to yourself, "Fine and good, I have the two entries I need, but shouldn't there be a link between Hotel and its Annotation?"

Thank you for asking. I show you how to do that now.

Now, if I had my druthers, I'd rather have set up title subtitle, latitude, and longitude as part of the Hotel entry, but doing it this way means I get to show you how to create a relation between two entities.

When you're done, your model should look like what you see in Figure 4-16.

Figure 4-16. The Hotel with its relationship to Annotation.

You also may want to be able to reference Hotel from its annotation, so let me show you how to do that as well.

Next you want to refine the relationship a bit more. You need to create an inverse relationship between Hotel and Annotation. That means when Core Data loads your objects, they will point to each other.

You usually model relationships in both directions and specify the inverse relationships accordingly. Core Data uses this information to ensure consistency when a change is made to one or the other.

Make sure Annotation is selected in the Entity pane and then choose Annotation from the Detail pane's Inverse pop-up menu as I have in Figure 4-18.

Figure 4-17. Relationships from Hotel to Annotation and Annotation to Hotel.

Figure 4-18. Setting an inverse relationship.

When you're done, your data model should look like Figure 4-19.

Figure 4-19. The inverse relationship.

Of course, you still need the classes for your program. Remember, all you've done thus far is create a data model for Core Data to use to both save and get your objects. You'll still need the classes to describe them in your program.

Does that mean a lot of copy and paste? Of course not. You can now use Xcode to generate the files for your Hotel and Annotation classes.

#import <CoreData/CoreData.h>

@class Annotation;

@interface Hotel :  NSManagedObject
{
}

@property (nonatomic, retain) NSString * street;
@property (nonatomic, retain) NSString * state;
@property (nonatomic, retain) NSString * zip;
@property (nonatomic, retain) NSString * name;
@property (nonatomic, retain) NSString * city;
@property (nonatomic, retain) Annotation * annotation;

@end

#import "Hotel.h"

#import "Annotation.h"

@implementation Hotel

@dynamic street;
@dynamic state;
@dynamic zip;
@dynamic name;
@dynamic city;
@dynamic annotation;

@end

@class Hotel;

@interface Annotation :  NSManagedObject
{
}

@property (nonatomic, retain) NSString * title;
@property (nonatomic, retain) NSNumber * latitude;
@property (nonatomic, retain) NSNumber * longitude;
@property (nonatomic, retain) NSString * subtitle;
@property (nonatomic, retain) Hotel * hotel;

@end

#import "Annotation.h"

#import "Hotel.h"

@implementation Annotation

@dynamic title;
@dynamic latitude;
@dynamic longitude;
@dynamic subtitle;
@dynamic hotel;

@end

There are a few things you should probably notice

You also have to add a few things to Annotation.h to make it work. Add the code in bold in Listing 4-7.

#import <CoreData/CoreData.h>

@class Hotel;
#import <MapKit/MapKit.h>

@interface Annotation :  NSManagedObject  <MKAnnotation>
{
CLLocationCoordinate2D coordinate;
}

@property (nonatomic, retain) NSString * title;
@property (nonatomic, retain) NSNumber * latitude;
@property (nonatomic, retain) NSNumber * longitude;
@property (nonatomic, retain) NSString * subtitle;
@property (nonatomic, retain) Hotel * hotel;
@property (nonatomic) CLLocationCoordinate2D coordinate;
- (NSString *) title;
- (NSString *) subtitle;

@end

You've both adopted and added the required methods and properties for the MKAnnotation protocol. Although I could have simply used the title and subtitle properties as is, I want to make you more comfortable with treating the generated classes like you would any other — say, by adding methods or even by adding methods that override the generated accessors.

You also have to implement the new methods in the Annotation.m file. Add the code in bold in Listing 4-8 to that file.

#import "Annotation.h"

#import "Hotel.h"

@implementation Annotation

@dynamic title;
@dynamic latitude;
@dynamic longitude;
@dynamic subtitle;
@dynamic hotel;
@synthesize coordinate;

- (CLLocationCoordinate2D) coordinate {

  CLLocationCoordinate2D theCoordinate;
  theCoordinate.latitude = [self.latitude doubleValue];
  theCoordinate.longitude = [self.longitude doubleValue];
  return theCoordinate;
}


- (NSString *) title {
  return self.hotel.name;
}
- (NSString *) subtitle {
   return self.hotel.city;
}

@end

You'll also notice one other thing. Instead of being derived from NSObject, Hotel, and Annotation are derived from NSManagedObject. Read on to find out why Managed slipped its way between NS and Object.

NSManagedObject contains the methods and properties necessary to represent any entity. It has a reference to the entity description for the entity of which it is an instance — and using the information in the entity description, information about its attributes and relationships. You can also create subclasses of NSManagedObject to implement additional behavior.

If you feel so inclined, you can think of a managed object as the object representation of a record in a table in a database. Each managed object represents the data you operate on in your application — in this case Hotel objects and their associated data — name, street address, city, state, and zip code. You can even add in reservation data and conformation number at your leisure.

NSManagedObject connects your objects to the Managed Object Context, as explained in the next section.

Way back when you created the RoadTrip project, I told you to use XCode's Project template for a navigation-based application, but to leave the Use Core Data for Storage check box deselected.

If you had selected that check box way back when, you would have found yourself with an application that had Core Data firmly integrated into your application. You'd find the Core Data stack in your application delegate, and you'd find a RootViewController that used Core Data as well. Although letting Xcode do it might appear to be easier, figuring out how to retrofit Core Data into an existing application is something you'll want to know how to do, and doing so will give you a better understanding of how it all works.

That being the case, you still don't want to have to type all that code in by hand, so in this section I show you how to have the best of both worlds.

To start with, I want you to create a new, throw-away project. Use the Navigation-Based Application template you see in Figure 4-23, but this time select the check box that says Use Core Data for Storage. (If you need a refresher on how to set up a project in Xcode, take another look at Book V, Chapter 1.)

Figure 4-23. The avigation-Based Application template.

You can name the application anything you'd like, but I use CoreData.

In this new project you just created out of thin air, you'll find that the template contains all you need to set up Core Data, and all you really need to do is copy the generated code into your RoadTrip project. Here's the blow by blow:

In your throw-away project, the Core Data Stack is, of course, in the application delegate. In this example, I've shown you how to have it owned by the model instead — with a little help from the Copy and Paste commands.

Okay, you have a Core Data Stack, which, admit it, didn't require much heavy lifting. Next you have to add the Core Data Framework.

Up until now, all you've needed to get by is the framework that more or less came supplied when you created a project. (Except for MapKit back in Book V, Chapter 5, of course, but that was the exception that proved the rule.) Now you need a new framework to enable Core Data.

Clean up time. You're going to have to add some instance variables and properties and a method to the Trip.h file — no ifs, ands, or buts about it. Make the modifications you see bolded in Listing 4-9.

#import <MapKit/MapKit.h>
#import <Foundation/Foundation.h>
@class Weather;
@class CarServicing;
@class CarInformation;
@class Map;
@class MapController;

@interface Trip : NSObject  {

  NSString       *tripName;
  CarServicing   *carServicing;
  CarInformation *carInformation;
  Weather        *weather;
  NSMutableArray *sights;
  Map            *map;
  MapController  *mapController;

// Core Data Stack
  NSManagedObjectModel *managedObjectModel;
  NSManagedObjectContext *managedObjectContext;
  NSPersistentStoreCoordinator *persistentStoreCoordinator;

}

@property (nonatomic, retain) NSMutableArray *sights;
@property (nonatomic, retain) Map* map;
@property (nonatomic, retain) MapController *mapController;

- (NSString *)applicationDocumentsDirectory;

- (id) initWithName:(NSString*) theTripName;
- (CLLocationCoordinate2D) initialCoordinate;
- (NSString*) mapTitle;
- (id) returnSightDelegate:(int) index;
- (id) returnWeatherDelegate;
- (id) returnCarInformationDelegate;
- (id) returnCarServicingDelegate;

// Core data properties and method
@property (nonatomic, retain, readonly) NSManagedObjectModel
   *managedObjectModel;
@property (nonatomic, retain, readonly)
   NSManagedObjectContext *managedObjectContext;
@property (nonatomic, retain, readonly)
   NSPersistentStoreCoordinator *persistentStoreCoordinator;
- (NSString *)applicationDocumentsDirectory;


@end

Notice that the properties you just added are readonly.

One more thing left to do. You need to add something to the RoadTrip_Prefix.pch file in the Other Sources folder in Groups & Files list. (Figure 4-28 shows you the innards of the RoadTrip_Prefix.pch file.)

Figure 4-28. Add to the Road Trip_Prefix.pch file.

You have to add Core Data to the RoadTrip_Prefix.pch file to make sure it is included wherever you need it. To do so, add the code in bold in Listing 4-10 to the file.

#import <Availability.h>

#ifndef __IPHONE_3_0
#warning "This project uses features only available in iPhone
   SDK 3.0 and later."
#endif

#ifdef __OBJC__
    #import <Foundation/Foundation.h>
    #import <UIKit/UIKit.h>
    #import <CoreData/CoreData.h>

#endif

@end

You're now ready to actually use Core Data. Your project should compile and execute with no errors.

Listing 4-11 shows you the code for accessing the managedObjectContext property. It's actually an explicit implementation of the managedObjectContext property getter and is invoked every time you access the property.

It returns the NSManagedObjectContext for the application. If the context doesn't already exist, it is created and bound to the persistent store coordinator for the application.

- (NSManagedObjectContext *) managedObjectContext {

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

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

Notice that it uses (and sets) the persistentStoreCoordinator.

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

Listing 4-12 shows the code for accessing the persistentStoreCoordinator Property. It works the same way — as an explicit implementation of the persistentStoreCoordinator property getter and is invoked every time you access the property.

It returns the NSPersistentStoreCoordinator for the application. If the coordinator doesn't already exist, it's created, and the application's store is added to it.

- (NSPersistentStoreCoordinator *)
                              persistentStoreCoordinator {

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

    NSURL *storeUrl = [NSURL fileURLWithPath:
     [[self applicationDocumentsDirectory]
     stringByAppendingPathComponent:@"CoreData.sqlite"]];

    NSError *error = nil;
    persistentStoreCoordinator =
       [[NSPersistentStoreCoordinator alloc]
       initWithManagedObjectModel:
                               [self managedObjectModel]];
    if (![persistentStoreCoordinator addPersistentStoreWit
   hType:NSSQLiteStoreType configuration:nil URL:storeUrl
   options:nil error:&error]) {
                                                        /*
   Replace this implementation with code to handle the error
   appropriately.
                                                        */
   NSLog(@"Unresolved error %@, %@", error,
                                        [error userInfo]);
   abort();
    }

    return persistentStoreCoordinator;
}

Notice the persistent store uses SQLite as its store, although you can use others.

NSURL *storeUrl = [NSURL fileURLWithPath:
 [[self applicationDocumentsDirectory]
     stringByAppendingPathComponent:@"CoreData.sqlite"]];

if (![persistentStoreCoordinator
      addPersistentStoreWithType:NSSQLiteStoreType
      configuration:nil URL:storeUrl options:nil
                                          error:&error]) {

You'll see this error (in addition to when the store is not accessible) when the schema for the persistent store is incompatible with current Managed Object Model. And that happens when you change the Managed Object Model (which happens frequently during development) and either don't migrate to the new one (out of scope for this book) or delete the old one and start from scratch.

The current code uses abort() when that happens — causing the application to generate a crash log and terminate. Although it may be useful during development, you shouldn't do this in a shipping application. You should at least display an alert that instructs the user what has happened and/or what to do.

Notice it uses the applicationDocumentsDirectory.

NSURL *storeUrl = [NSURL fileURLWithPath:
     [[self applicationDocumentsDirectory]
     stringByAppendingPathComponent:@"CoreData.sqlite"]];

Listing 4-13 shows how the path to the application's Documents directory is returned.

- (NSString *)applicationDocumentsDirectory {
   return [NSSearchPathForDirectoriesInDomains(NSDocumentDire
   ctory, NSUserDomainMask, YES) lastObject];
}

Also notice that the Persistent Store Coordinator uses the managedObjectModel property.

persistentStoreCoordinator =
   [[NSPersistentStoreCoordinator alloc]
   initWithManagedObjectModel: [self managedObjectModel]];

Listing 4-14 shows you the code for accessing the managedObjectModel property. It, too, is an explicit implementation of the managedObjectModel property getter and is invoked every time you access the property. As you saw, it's accessed when you create the Persistent Store Coordinator.

It returns the Managed Object Model for the application. If the model doesn't already exist, it is created by merging all of the models found in the application bundle.

- (NSManagedObjectModel *)managedObjectModel {

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