Designing the Persistence Application View

Now select Main.storyboard to edit the GUI. Once Xcode switches over to Interface Builder mode, you’ll see the View Controller scene in the editing pane. Drag a Text Field from the library and place it against the top and right blue guidelines. Bring up the Attributes Inspector. Make sure the box labeled Clear When Editing Begins is unchecked.

Now drag a Label to the window and place it to the left of the text field using the left blue guideline, and then use the horizontal blue guideline to line up the label’s vertical center with that of the text field. Double-click the label and change it to say Line 1:. Finally, resize the text field using the left resize handle to bring it close to the label. Use Figure 13-6 as a guide. Next, select the label and text field, hold down the Option key, and drag down to make a copy below the first set. Use the blue guidelines to guide your placement. Now select both labels and both text fields, hold down the Option key, and drag down again. You should now have four labels next to four text fields. Double-click each of the remaining labels and change their names to Line 2:, Line 3:, and Line 4:. Again, compare your results with Figure 13-6.

Figure 13-6. Designing the Persistence application’s view

Once you have all four text fields and labels placed, Control-drag from the View Controller icon in the Document Outline to each of the four text fields. Connect them all to the lineFields outlet collection, making sure to connect them in order from top to bottom. Save the changes you made to Main.storyboard.

Now let’s add the Auto Layout constraints to make sure that the design works the same way on all devices. Starting by Control-dragging from the Line 1 label to the text field to its right, and then release the mouse. Hold down the Shift key and select Horizontal Spacing and Baseline, and then click the Return key. Do the same for the other three labels and text fields.

Next, we’ll fix the positions of the text fields. In the Document Outline, Control-drag from the top text field to its parent View icon, release the mouse, hold down the Shift key, and select Trailing Space to Container Margin and Vertical Spacing to Top Layout Guide. Do the same for the other three text fields.

We need to fix the widths of the labels so that they don’t resize if the user types more text than will fit in any of the text fields. Select the top label and click the Pin button below the storyboard editor. In the pop-up, select the Width check box and press Add 1 Constraint. Do the same for all of the labels.

Finally, back in the Document Outline, Control-drag from the Line 1 label to the View icon, release the mouse, and select Leading Space to Container Margin. Do the same for all of the labels and that’s it—all the required Auto Layout constraints have been set. Select the view controller icon in the Document Outline followed by Editor ➤ Resolve Auto Layout Issues ➤ Update Frames in the menu to remove the warnings in the Xcode Activity View. Now build and run the application and compare the result with Figure 13-6.

Editing the Persistence Classes

In the Project Navigator, select ViewController.swift and add the code in Listing 13-6.

Listing 13-6. Getting the URL for Our data.plist File

func dataFileURL() -> NSURL {
    let urls = FileManager.default.urls(for:
        .documentDirectory, in: .userDomainMask)
    var url:NSURL?
    url = URL(fileURLWithPath: "")      // create a blank path
    do {
        try url = urls.first!.appendingPathComponent("data.plist")
    } catch  {
        print("Error is (error)")
    }
    return url!
}

The dataFileURL() method returns the URL of the data file that we’ll be creating in this example by finding the Documents directory and appending the file name to it. This method will be called from any code that needs to load or save data. We are playing it a little loose here with the url. Note that we’ve encapsulated the appendingPathComponent method within a Swift do-catch block. We have to do this because the append method throws an error that needs to be caught. But since we know that our app bundle must have a document directory and we’re creating the data.plist file ourselves, we’re not going to see this error as long as we write the code correctly. Normally, we want to handle things a little more securely so our customers don’t see crashes, but for the sake of brevity we’re not going to deal with that here since it’s not the subject of our discussion.

Find the viewDidLoad() method and add the following code to it, as well as a new method for receiving notifications named applicationWillResignActive() just below it, as shown in Listing 13-7.

Listing 13-7. The viewDidLoad method in the ViewController.swift file and the applicationWillResignActive method.

override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view, typically from a nib.
    let fileURL = self.dataFileURL()
    if (FileManager.default.fileExists(atPath: fileURL.path!)) {
        if let array = NSArray(contentsOf: fileURL as URL) as? [String] {
            for i in 0..<array.count {
                lineFields[i].text = array[i]
            }
        }
    }

let app = UIApplication.shared()
    NotificationCenter.default.addObserver(self, selector: #selector(self.applicationWillResignActive(notification:)), name: Notification.Name.UIApplicationWillResignActive, object: app)
}

func applicationWillResignActive(notification:NSNotification) {
    let fileURL = self.dataFileURL()
    let array = (self.lineFields as NSArray).value(forKey: "text") as! NSArray
    array.write(to: fileURL as URL, atomically: true)
}

In the viewDidLoad() method , we do a few more things. First, we use the fileExists(atPath:) method of the FileManager class to check whether our data file already exists, which would be the case if we have already run the application at least once. This method requires the file’s path name, which we get from the path property of its URL (unfortunately, there isn’t a variant of this method that accepts a URL argument). If there isn’t one, we don’t want to bother trying to load it. If the file does exist, we instantiate an array with the contents of that file, and then copy the objects from that array to our four text fields. Because arrays are ordered lists, we copy them in the same order as we saved them

To read the file, we use an Array initializer that creates an NSArray object from the contents of a file at a given URL. The Array initializer expects the file content to be in property list format, which is fine because that’s the form in which it is saved, in the code we’ll write shortly.

Our application needs to save its data before it is terminated or sent to the background, so we are interested in the notification called applicationWillResignActive. This notification is posted whenever an app is no longer the one with which the user is interacting. This happens when the user taps the Home button, as well as when the application is pushed to the background by some other event, such as an incoming phone call. We can find out that this has happened by registering for a notification from iOS’s notification center. The notification center delivers a notification by calling a method that you register with it, passing an argument of type Notification that includes the details of the event that’s being notified. To register for this notification, we get a reference to our application instance and use that to subscribe to UIApplicationWillResignActive, using the default NotificationCenter instance and a method called addObserver(_:selector:name:object:). We pass self as the first parameter, specifying that our ViewController instance is the observer that should be notified. For the second parameter, we pass a selector to the applicationWillResignActive() method , telling the notification center to call that method when the notification is posted. The third parameter, UIApplicationWillResignActive, is the name of the notification that we’re interested in receiving. This is a string constant defined by the UIApplication class.

Finally, we added the implementation of the applicationWillResignActive() method , which the notification center will call:

    func applicationWillResignActive(notification:NSNotification) {
        let fileURL = self.dataFileURL()
        let array = (self.lineFields as NSArray).value(forKey: "text") as! NSArray
        array.write(to: fileURL as URL, atomically: true)
    }

This method is pretty short, but really does a lot with just a few method calls. We construct an array of strings by calling the text method on each of the text fields in our lineFields array. To accomplish this, we use a clever shortcut: instead of explicitly iterating through our array of text fields, asking each for its text value, and adding that value to a new array, we cast the Swift lineFields array (of UITextFields) to an NSArray and call value(forKey:) on it, passing "text" as a parameter. The NSArray implementation of valueForKey()does the iteration for us, asks each UITextField instance it contains for its text value, and returns a new NSArray containing all the values. After that, we write the contents of that array out to our .plist file in property list format, using the write(_ to:atomically:) method . That’s all there is to saving our data using property lists.

Let’s summarize how this works. When our main view is finished loading, we look for a .plist file. If it exists, we copy data from it into our text fields. Next, we register to be notified when the application becomes inactive (either by being quit or pushed to the background). When that happens, we gather the values from our four text fields, stick them in a mutable array, and write that mutable array to a property list.

Build and run the application. It should build and then launch in the simulator. Once it comes up, you should be able to type into any of the four text fields. When you’ve typed something in them, press ⌘⇧H (Command-Shift-H) to return to the home screen. It’s very important that you do this. If you just exit the simulator, that’s the equivalent of forcibly quitting your application. In that case, the view controller will never receive the notification that the application is going inactive, and your data will not be saved. After returning to the home screen, you may then quit the simulator, or stop the app from Xcode and run it again. Your text will be restored and will appear in the text fields the next time the app starts.

Property list serialization is pretty cool and easy to use. However, it’s a little limiting, since only a small selection of objects can be stored in property lists. Let’s look at a somewhat more robust approach.

Implementing the FourLines Class

Once you’re ready to proceed and have a copy of your Persistence project open in Xcode, press ⌘N or select File ➤ New ➤ File.... When the new file assistant comes up, from the iOS section, select Swift File and click Next. On the next screen, name the file FourLines.swift, choose the Persistence folder to save it, and then click Create. This class is going to be our data model. It will hold the data that we’re currently storing in a dictionary in the property list application.

Single-click FourLines.swift and add the code in Listing 13-8.

Listing 13-8. Our FourLines Class

class FourLines : NSObject, NSCoding, NSCopying {
    private static let linesKey = "linesKey"
    var lines:[String]?
    override init() {
    }

    required init?(coder aDecoder: NSCoder) {
        lines = aDecoder.decodeObject(forKey: FourLines.linesKey) as? [String]
    }
    func encode(with aCoder: NSCoder) {
        if let saveLines = lines {
            aCoder.encode(saveLines, forKey: FourLines.linesKey)
        }
    }
    func copy(with zone: NSZone? = nil) -> AnyObject {
        let copy = FourLines()
        if let linesToCopy = lines {
            var newLines = Array<String>()
            for line in linesToCopy {
                newLines.append(line)
            }
            copy.lines = newLines
        }
        return copy
    }
}

We just implemented all the methods necessary to conform to the NSCoding and NSCopying protocols. We encoded the lines property in encode(with aCoder:) and decoded it using the same key value in init(with aCoder: ). In copy(with zone: ), we created a new FourLines object and copied the string array to it, carefully making a deep copy so that changes to the original will not affect the new object. See? It’s not hard at all; just make sure you did not forget to change anything if you did a lot of copying and pasting.

Implementing the ViewController Class

Now that we have an archivable data object, let’s use it to persist our application data. Select ViewController.swift and make the changes in Listing 13-9.

Listing 13-9. Our Save and Retrieve Code for Archiving Object in ViewController.swift

override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view, typically from a nib.
    let fileURL = self.dataFileURL()
    if (FileManager.default.fileExists(atPath: fileURL.path!)) {
        if let array = NSArray(contentsOf: fileURL as URL) as? [String] {
            for i in 0..<array.count {
                lineFields[i].text = array[i]
            }
        }
        let data = NSMutableData(contentsOf: fileURL as URL)
        let unarchiver = NSKeyedUnarchiver(forReadingWith: data as! Data)
        let fourLines = unarchiver.decodeObject(forKey: ViewController.rootKey) as! FourLines
        unarchiver.finishDecoding()

        if let newLines = fourLines.lines {
            for i in 0..<newLines.count {
                lineFields[i].text = newLines[i]
            }
        }
    }
    let app = UIApplication.shared()
    NotificationCenter.default.addObserver(self, selector: #selector(self.applicationWillResignActive(notification:)), name: Notification.Name.UIApplicationWillResignActive, object: app)
}

func applicationWillResignActive(notification:NSNotification) {
    let fileURL = self.dataFileURL()
    let fourLines = FourLines()
    let array = (self.lineFields as NSArray).value(forKey: "text")
        as! [String]
    fourLines.lines = array

    let data = NSMutableData()
    let archiver = NSKeyedArchiver(forWritingWith: data)
    archiver.encode(fourLines, forKey: ViewController.rootKey)
    archiver.finishEncoding()
    data.write(to: fileURL as URL, atomically: true)
}

func dataFileURL() -> NSURL {
    let urls = FileManager.default.urls(for:
        .documentDirectory, in: .userDomainMask)
    var url:NSURL?
    url = URL(fileURLWithPath: "")      // create a blank path
    do {
        try url = urls.first!.appendingPathComponent("data.archive")
    } catch  {
        print("Error is (error)")
    }
    return url!
}

Save your changes, then build and run this version of the app. Not very much has changed, really. We started off by specifying a new file name in the dataFileURL() method, so that our program doesn’t try to load the old property list as an archive. We also defined a new constant that will be the key value we use to encode and decode our object. Next, we redefined the loading and saving by using FourLines to hold the data and using its NSCoding methods to do the actual loading and saving. The GUI is identical to the previous version.

This new version takes several more lines of code to implement than property list serialization, so you might be wondering if there really is an advantage to using archiving over just serializing property lists. For this application, the answer is simple: no, there really isn’t any advantage. But imagine we had an array of archivable objects, such as the FourLines class that we just built, we could archive the entire array by archiving the array instance itself. Collection classes like Array, when archived, archive all of the objects they contain. As long as every object you put into an array or dictionary conforms to NSCoding, you can archive the array or dictionary and restore it so that all the objects that were in it when you archived it will be in the restored array or dictionary. The same is not true of property link persistence, which only works for a small set of Foundation object types—you cannot use it to persist custom classes without writing additional code to convert instances of those classes to and from a Dictionary, with one key for each object property.

In other words, the NSCoding approach scales beautifully (in terms of code size, at least). No matter how many objects you add, the work to write those objects to disk (assuming you’re using single-file persistence) is exactly the same. With property lists , the amount of work increases with every object you add.

Modifying the Persistence View Controller

Next, we need to import the header files for SQLite3 into the view controller so that the compiler can see the function and other definitions that make up the API. There is no way to directly import the header file into Swift code, because the SQLite3 library is not packaged as a framework. The easiest way to deal with this is to add a bridging headerto the project. Once you have a bridging header, you can add other header files to it, and those header files will be read by the Swift compiler. There are a couple of ways to add a bridging file. We’ll use the simpler of the two, which is to temporarily add an Objective-C class to the project. Let’s do that now.

Press ⌘N or select File ➤ New ➤ File.... In the iOS Source section of the dialog, choose Cocoa Touch Class and press Next. Name the class Temporary, make it a subclass of NSObject, change the language to Objective-C, and press Next. In the next screen, press the Create button. When you do this, Xcode will pop up a window asking whether you want to create a bridging header. Click Create Bridging Header. Now, in the Project Navigator, you’ll see the files for the new class (Temporary.m and Temporary.h) and the bridging header, which is called SQLite Persistence-Bridging-Header.h . Delete the Temporary.m and Temporary.h files—you don’t need them anymore. Select the bridging header to open it in the editor, and then add the following line to it:

#import <sqlite3.h>

Now that the compiler can see the SQLite3 library and header files, we can write some more code. Select ViewController.swift and make the changes shown in Listing 13-10.

Listing 13-10. Using SQLite3 to Save and Retrieve Our Information

override func viewDidLoad() {
    super.viewDidLoad()
    // Do any additional setup after loading the view, typically from a nib.
    var database:OpaquePointer? = nil
    var result = sqlite3_open(dataFilePath(), &database)
    if result != SQLITE_OK {
        sqlite3_close(database)
        print("Failed to open database")
        return
    }
    let createSQL = "CREATE TABLE IF NOT EXISTS FIELDS " +
                        "(ROW INTEGER PRIMARY KEY, FIELD_DATA TEXT);"
    var errMsg:UnsafeMutablePointer<Int8>? = nil
    result = sqlite3_exec(database, createSQL, nil, nil, &errMsg)
    if (result != SQLITE_OK) {
        sqlite3_close(database)
        print("Failed to create table")
        return
    }

    let query = "SELECT ROW, FIELD_DATA FROM FIELDS ORDER BY ROW"
    var statement:OpaquePointer? = nil
    if sqlite3_prepare_v2(database, query, -1, &statement, nil) == SQLITE_OK {
        while sqlite3_step(statement) == SQLITE_ROW {
            let row = Int(sqlite3_column_int(statement, 0))
            let rowData = sqlite3_column_text(statement, 1)
            let fieldValue = String.init(cString: UnsafePointer<CChar>(rowData!))
            lineFields[row].text = fieldValue
        }
        sqlite3_finalize(statement)
    }
    sqlite3_close(database)

    let app = UIApplication.shared()
    NotificationCenter.default.addObserver(self, selector: #selector(self.applicationWillResignActive(notification:)), name: Notification.Name.UIApplicationWillResignActive, object: app)

}

func dataFilePath() -> String {
    let urls = FileManager.default.urls(for:
        .documentDirectory, in: .userDomainMask)
    var url:String?
    url = ""      // create a blank path                                                                          
    do {
        try url = urls.first?.appendingPathComponent("data.plist").path!
    } catch  {
        print("Error is (error)")
    }
    return url!
}

func applicationWillResignActive(notification:NSNotification) {
    var database:OpaquePointer? = nil
    let result = sqlite3_open(dataFilePath(), &database)
    if result != SQLITE_OK {
        sqlite3_close(database)
        print("Failed to open database")
        return
    }
    for i in 0..<lineFields.count  {
        let field = lineFields[i]
        let update = "INSERT OR REPLACE INTO FIELDS (ROW, FIELD_DATA) " +
        "VALUES (?, ?);"
        var statement:OpaquePointer? = nil
        if sqlite3_prepare_v2(database, update, -1, &statement, nil) == SQLITE_OK {
            let text = field.text
            sqlite3_bind_int(statement, 1, Int32(i))
            sqlite3_bind_text(statement, 2, text!, -1, nil)
        }
        if sqlite3_step(statement) != SQLITE_DONE {
            print("Error updating table")
            sqlite3_close(database)
            return
        }
        sqlite3_finalize(statement)
    }
    sqlite3_close(database)
}

The first piece of new code is in the viewDidLoad() method . We begin by getting the path to the database file using the dataFilePath() method that we added. This is just like the dataFileURL() method that we added to our earlier examples, except that it returns the file’s path not its URL. That’s because the SQLite3 APIs that work with files require paths, not URLs. Next, we use the path to open the database, creating it if it does not exist. If we hit a problem with opening the database, we close it, print an error message , and return:

        var database:OpaquePointer? = nil
        var result = sqlite3_open(dataFilePath(), &database)
        if result != SQLITE_OK {
            sqlite3_close(database)
            print("Failed to open database")
            return
        }

Next, we need to make sure that we have a table to hold our data. We use an SQL CREATE TABLE statement to do that. By specifying IF NOT EXISTS, we prevent the database from overwriting existing data—if there is already a table with the same name, this command quietly completes without doing anything. That means it’s safe to use it every time our application launches without explicitly checking to see if a table exists:

        let createSQL = "CREATE TABLE IF NOT EXISTS FIELDS " +
                            "(ROW INTEGER PRIMARY KEY, FIELD_DATA TEXT);"
        var errMsg:UnsafeMutablePointer<Int8>? = nil
        result = sqlite3_exec(database, createSQL, nil, nil, &errMsg)
        if (result != SQLITE_OK) {
            sqlite3_close(database)
            print("Failed to create table")
            return
        }

Each row in the database table contains an integer and a string. The integer is the number of the row in the GUI from which the data was obtained (starting from zero), and the string is the content of the text field on that row. Finally, we need to load our data. We do this using an SQL SELECT statement . In this simple example, we create an SQL SELECT statement that requests all the rows from the database and then we ask SQLite3 to prepare our SELECT. We also tell SQLite3 to order the rows by the row number, so that we always get them back in the same order. Absent this, SQLite3 will return the rows in the order in which they are stored internally.

        let query = "SELECT ROW, FIELD_DATA FROM FIELDS ORDER BY ROW"
        var statement:OpaquePointer? = nil
        if sqlite3_prepare_v2(database, query, -1, &statement, nil) == SQLITE_OK {

Next, we use the sqlite3_step() function to execute the SELECT statement and step through each of the returned rows:

            while sqlite3_step(statement) == SQLITE_ROW {

Now we grab the row number, store it in an int, and then grab the field data as a C string, which we then convert to a Swift String, as described earlier in the chapter:

        let row = Int(sqlite3_column_int(statement, 0))
        let rowData = sqlite3_column_text(statement, 1)
        let fieldValue = String.init(cString: UnsafePointer<CChar>(rowData!))

Next, we set the appropriate field with the value retrieved from the database:

        lineFields[row].text = fieldValue

Finally, we close the database connection , and we’re finished:

        }
        sqlite3_finalize(statement)
    }
    sqlite3_close(database)

Note that we close the database connection as soon as we’re finished creating the table and loading any data it contains, rather than keeping it open the entire time the application is running. It’s the simplest way of managing the connection; and in this little app, we can just open the connection those few times we need it. In a more database-intensive app, you might want to keep the connection open all the time.

The other changes we made are in the applicationWillResignActive() method , where we need to save our application data.

The applicationWillResignActive() method starts by once again opening the database. To save the data, we loop through all four fields and issue a separate command to update each row of the database:

        for i in 0..<lineFields.count  {
            let field = lineFields[i]

We craft an INSERT OR REPLACE SQL statement with two bind variables. The first represents the row that’s being stored; the second is for the actual string value to be stored. By using INSERT OR REPLACE instead of the more standard INSERT, we don’t need to worry about whether a row already exists:

        let update = "INSERT OR REPLACE INTO FIELDS (ROW, FIELD_DATA) " +
                      "VALUES (?, ?);"

Next, we declare a pointer to a statement, prepare our statement with the bind variables, and bind values to both of the bind variables :

            var statement:OpaquePointer? = nil
            if sqlite3_prepare_v2(database, update, -1, &statement, nil) == SQLITE_OK {
                let text = field.text
                sqlite3_bind_int(statement, 1, Int32(i))
                sqlite3_bind_text(statement, 2, text!, -1, nil)
            }

Now we call sqlite3_step to execute the update, check to make sure it worked, and finalize the statement, ending the loop:

            if sqlite3_step(statement) != SQLITE_DONE {
                print("Error updating table")
                sqlite3_close(database)
                return
            }
            sqlite3_finalize(statement)

Notice that we simply print an error message here if anything goes wrong. In a real application, if an error condition is one that a user might reasonably experience, you should use some other form of error reporting, such as popping up an alert box .

    sqlite3_close(database)

Build and run the app. Enter some data and then press the iPhone simulator’s Home button. Quit the simulator (to force the app to actually quit), and then relaunch the SQLite Persistence application. That data should be right where you left it. As far as the user is concerned, there’s absolutely no difference between the various versions of this application; however, each version uses a different persistence mechanism.

Key-Value Coding

In your code, instead of using accessors and mutators, you will use key-value coding to set properties or retrieve their existing values. Key-value coding may sound intimidating, but you’ve already used it quite a bit in this book. Every time we used Dictionary, for example, we were using a form of key-value coding because every object in a dictionary is stored under a unique key value. The key-value coding used by Core Data is a bit more complex than that used by Dictionary, but the basic concept is the same. When working with a managed object, the key you will use to set or retrieve a property’s value is the name of the attribute you wish to set. So, here’s how to retrieve the value stored in the attribute called name from a managed object:

let name = myManagedObject.valueForKey("name")

Similarly, to set a new value for a managed object’s property, do this:

myManagedObject.setValue("Gregor Overlander", forKey:"name")

Putting It All in Context

So where do these managed objects live? They live in something called a persistent store, also referred to as a backing store. Persistent stores can take several different forms. By default, a Core Data application implements a backing store as an SQLite database stored in the application’s Documents directory. Even though your data is stored via SQLite, classes in the Core Data framework do all the work associated with loading and saving your data. If you use Core Data, you don’t need to write any SQL statements like the ones you saw in the SQLite Persistence application. You just work with objects, and Core Data figures out what it needs to do behind the scenes.

SQLite isn’t the only option Core Data has for storage. Backing stores can also be implemented as binary flat files or even stored in an XML format. Another option is to create an in-memory store, which you might use if you’re writing a caching mechanism; however, it doesn’t save data beyond the end of the current session. In almost all situations, you should just leave it as the default and use SQLite as your persistent store.

Although most applications will have only one persistent store, it is possible to have multiple persistent stores within the same application. If you’re curious about how the backing store is created and configured, take a look at the file AppDelegate.swift in your Xcode project. The Xcode project template we chose provided us with all the code needed to set up a single persistent store for our application.

Other than creating it, you generally won’t work with your persistent store directly. Rather, you will use something called a managed object context, often referred to as just a context. The context manages access to the persistent store and maintains information about which properties have changed since the last time an object was saved. The context also registers all changes with the undo manager, which means that you always have the ability to undo a single change or roll back all the way to the last time data was saved.

Many Core Data method calls require an NSManagedObjectContextas a parameter or must be executed against a context. With the exception of more complicated, multithreaded iOS applications, you can just use the managedObjectContext property provided by your application delegate, which is a default context that is created for you automatically, also courtesy of the Xcode project template.

You may notice that in addition to a managed object context and a persistent store coordinator, the provided application delegate also contains an instance of NSManagedObjectModel. This class is responsible for loading and representing, at runtime, the data model you will create using the data model editor in Xcode. You generally won’t need to interact directly with this class. It’s used behind the scenes by the other Core Data classes, so they can identify which entities and properties you’ve defined in your data model. As long as you create your data model using the provided file, there’s no need to worry about this class at all.

Creating New Managed Objects

Creating a new instance of a managed object is pretty easy, though not quite as straightforward as creating a normal object instance. Instead, you use the insertNewObject( forEntityName: into:) factory method in a class called NSEntityDescription. NSEntityDescription’s job is to keep track of all the entities defined in the app’s data model and to let you create instances of those entities. This method creates and returns an instance representing a single entity in memory. It returns either an instance of NSManagedObject that is set up with the correct properties for that particular entity; or, if you’ve configured your entity to be implemented with a specific subclass of NSManagedObject, an instance of that class. Remember that entities are like classes. An entity is a description of an object and defines which properties a particular entity has.

To create a new object, do this:

    let thing = NSEntityDescription.insertNewObject (forEntityName: "Thing",
                                       into:managedObjectContext)

The method is called insertNewObject( forEntityName: into:)because, in addition to creating the object, it inserts the newly created object into the context and then returns that object. After this call, the object exists in the context, but is not yet part of the persistent store. The object will be added to the persistent store the next time the managed object context’s save() method is called.

Retrieving Managed Objects

To retrieve managed objects from the persistent store, you’ll use a fetch request, which is Core Data’s way of handling a predefined query. For example, you might say, “Give me every Person whose eyeColor is blue.” To create a fetch request, you provide it with an NSEntityDescription that specifies the entity of the object or objects you wish to retrieve. Here is an example that creates a fetch request:

let context = appDelegate.managedObjectContext
let request: NSFetchRequest<NSFetchRequestResult> = NSFetchRequest(entityName:”Thing”)

You execute the fetch request using an instance method on NSManagedObjectContext:

        do {
            let objects = try context.fetch(request)
            // No error - use "objects"
        } catch {
              // Error - the "error" variable contains an NSError object
          print(error)
        }

fetch() will load the specified objects from the persistent store and return them in an optional array. If an error is encountered, fetch() throws an NSError object that describes the specific problem. You need to either catch this error and handle it if at all possible, or let it propagate to the caller of the function that contains this code. Here, we just write the error to the console. If you are not familiar with Swift’s error handling mechanisms, refer to the section “Error Handling” in the Appendix. If no error occurs, you will get a valid array, though it may not have any objects in it since it is possible that none meets the specified criteria. From this point on, any changes you make to the managed objects returned in that array will be tracked by the managed object context you executed the request against, and saved when you send that context a save: message.

Designing the Data Model

Select Core_Data_Persistence.xcdatamodel to open Xcode’s data model editor. The data model editing pane shows all the entities, fetch requests, and configurations that are contained within your data model.

As shown in Figure 13-9, those lists are empty now because we haven’t created anything yet. Remedy that by clicking the plus icon labeled Add Entity in the lower-left corner of the editor pane. This will create a brand-new entity with the name Entity, as shown in Figure 13-10.

Figure 13-10. The data model editor, showing our newly added entity

As you build your data model, you’ll probably find yourself switching between Table view and Graph view using the Editor Style control at the bottom right of the editing area. Switch to Graph view now. Graph view presents a little box representing our entity, which itself contains sections for showing the entity’s attributes and relationships, also currently empty (see Figure 13-11). Graph view is really useful if your model contains multiple entities, because it shows a graphic representation of all the relationships between your entities.

Figure 13-11. Using the control in the lower-right corner, we switched the data model editor into Graph mode. Note that Graph mode shows the same entities as Table mode , just in a graphic form. This is useful if you have multiple entities with relationships between them

Whether you’re using Table view or Graph view for designing your data model, you’ll almost always want to bring up the Core Data data model inspector. This inspector lets you view and edit relevant details for whatever item is selected in the data model editor—whether it’s an entity, attribute, relationship, or anything else. You can browse an existing model without the data model inspector; but to really work on a model, you’ll invariably need to use this inspector, much as you frequently use the Attributes Inspector when editing nib files.

Press ⌥⌘3 to open the data model inspector. At the moment, the inspector shows information about the entity we just added. The single entity in our model contains the data from one line on the GUI, so we’ll call it Line. Change the Name field from Entity to Line , as shown in Figure 13-12.

Figure 13-12. Using the data model inspector to change our entity’s name to Line

If you’re currently in Graph view, use the Editor Style control to switch back to Table view. Table view shows more details for each piece of the entity we’re working on, so it’s usually more useful than Graph view when creating a new entity. In Table view, most of the data model editor is taken up by the table showing the entity’s attributes, relationships, and fetched properties. This is where we’ll set up our entity.

Notice that at the lower right of the editing area, next to the Editor Style control , there’s an icon containing a plus sign, labeled Add Attribute. If you select your entity and then hold down the mouse button over this control, a pop-up menu will appear, allowing you to add an attribute, relationship, or fetched property to your entity (see Figure 13-13). Alternatively, if you just want to add an attribute, you can simply click the plus icon.

Figure 13-13. With an entity selected, press and hold the right plus-sign icon to add an attribute, relationship, or fetched property to your entity

Go ahead and use this technique to add an attribute to your Line entity. A new attribute, creatively named attribute, is added to the Attributes section of the table and selected. In the table, you’ll see that not only is the row selected, but the attribute’s name is selected as well. This means that immediately after clicking the plus sign, you can start typing the name of the new attribute without further clicking. Change the new attribute’s name from attribute to lineNumber , and click the pop-up next to the name to change its Type from Undefined to Integer 16 . Doing so turns this attribute into one that will hold an integer value. We will be using this attribute to identify which of the managed object’s four fields holds data. Since we have only four options, we selected the smallest integer type available.

Now direct your attention to the data model inspector, which is in the pane to the right of the editor area. Here, additional details can be configured. The inspector should be showing properties for the attribute you just added. If it’s still showing details of the Line entity , click the attribute row in the editor to select it and the inspector should switch its focus to the attribute. The check box below the Name field on the right, Optional, is selected by default. Click it to deselect it. We don’t want this attribute to be optional—a line that doesn’t correspond to a label on our interface is useless.

Selecting the Transient check box creates a transient attribute. This attribute is used to specify a value that is held by managed objects while the app is running, but is never saved to the data store. We do want the line number saved to the data store, so leave the Transient check box unchecked. Selecting the Indexed check box will cause an index in the underlying SQL database to be created on the column that holds this attribute’s data. Leave the Indexed check box unchecked. The amount of data is small and we won’t provide the user with a search capability; therefore, there’s no need for an index.

Beneath that are more settings that allow us to do some simple data validation by specifying minimum and maximum values for the integer, a default value, and more. We won’t be using any of these settings in this example.

Now make sure the Line entity is selected and click the Add Attribute control to add a second attribute. Change the name of your new attribute to lineTextand change its Type to String. This attribute will hold the actual data from the text field. Leave the Optional check box checked for this one; it is altogether possible that the user won’t enter a value for a given field.

Our data model is complete. That’s all there is to it. Core Data lets you point and click your way to an application data model. Let’s finish building the application so you can see how to use our data model from our code.

Creating the Persistence View

Select ViewController.swift and make the following change shown in bold:

class ViewController: UIViewController {
    @IBOutlet var lineFields:[UITextField]!              

Save this file. Next, select Main.storyboard to edit the GUI in Interface Builder. Design the view and connect the outlet collection by following the instructions in the “Designing the Persistence Application View” section earlier in this chapter. You might also find it useful to refer back to Figure 13-6. Once your design is complete, save the storyboard file.

Now go back to ViewController.swift, and make the changes in Listing 13-13.

Listing 13-13. Modifying Our ViewController.swift file to Use Core Data

import UIKit
import CoreData

class ViewController: UIViewController {
    private static let lineEntityName = "Line"
    private static let lineNumberKey = "lineNumber"
    private static let lineTextKey = "lineText"
    @IBOutlet var lineFields:[UITextField]!

    override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view, typically from a nib.

        let appDelegate =
                    UIApplication.shared().delegate as! AppDelegate                                                      
        let context = appDelegate.managedObjectContext
        let request: NSFetchRequest<NSFetchRequestResult> = NSFetchRequest(entityName: ViewController.lineEntityName)

        do {
            let objects = try context.fetch(request)
            for object in objects {
                let lineNum: Int = object.value(forKey: ViewController.lineNumberKey)! as! Int
                let lineText = object.value(forKey: ViewController.lineTextKey) as? String ?? ""
                let textField = lineFields[lineNum]
                textField.text = lineText
            }

            let app = UIApplication.shared()
            NotificationCenter.default.addObserver(self,
                            selector: #selector(UIApplicationDelegate.applicationWillResignActive(_:)),
                            name: NSNotification.Name.UIApplicationWillResignActive,
                            object: app)
       } catch {
            // Error thrown from executeFetchRequest()
            print("There was an error in executeFetchRequest(): (error)")
       }
    }

    func applicationWillResignActive(_ notification:Notification) {
        let appDelegate =
            UIApplication.shared().delegate as! AppDelegate
        let context = appDelegate.managedObjectContext
        for i in 0 ..< lineFields.count {
            let textField = lineFields[i]

            let request: NSFetchRequest<NSFetchRequestResult> = NSFetchRequest(entityName: ViewController.lineEntityName)
            let pred = Predicate(format: "%K = %d", ViewController.lineNumberKey, i)
            request.predicate = pred

            do {
                let objects = try context.fetch(request)
                var theLine:NSManagedObject! = objects.first as? NSManagedObject
                if theLine == nil {
                    // No existing data for this row – insert a new managed object for it
                    theLine =
                        NSEntityDescription.insertNewObject(
                                forEntityName: ViewController.lineEntityName,
                                into: context)
                                as NSManagedObject
                }

                theLine.setValue(i, forKey: ViewController.lineNumberKey)
                theLine.setValue(textField.text, forKey: ViewController.lineTextKey)
            } catch {
                print("There was an error in executeFetchRequest(): (error)")
            }                                                                                      
        }
        appDelegate.saveContext()
    }
}

So that we can use Core Data, we imported the Core Data framework. Next, we modified the viewDidLoad() method , which needs to check whether there is any existing data in the persistent store. If there is, it should load the data and populate the text fields with it. The first thing we do in that method is get a reference to our application delegate, which we then use to get the managed object context (of type NSManagedObjectContext) that was created for us:

        let appDelegate =
                    UIApplication.shared().delegate as! AppDelegate
        let context = appDelegate.managedObjectContext

The next order of business is to create a fetch request and pass it the entity name, so it knows which type of objects to retrieve:

        let request: NSFetchRequest<NSFetchRequestResult> =
        NSFetchRequest(entityName: ViewController.lineEntityName)

Since we want to retrieve all Line objects in the persistent store, we do not create a predicate. By executing a request without a predicate, we’re telling the context to give us every Line object in the store. Having created the fetch request, we use the fetch() method of the managed object context to execute it. Since fetch() can throw an error, we place the call and the code that uses its results in a do-catch block, so that we can log the error, if there is one:

        do {
            let objects = try context.fetch(request)

Next, we loop through the array of retrieved managed objects, pull the lineNum and lineText values from each managed object, and use that information to update one of the text fields on our user interface :

            for object in objects {
                let lineNum: Int = object.value(forKey: ViewController.lineNumberKey)! as! Int
                let lineText = object.value(forKey: ViewController.lineTextKey) as? String ?? ""
                let textField = lineFields[lineNum]
                textField.text = lineText
            }

Of course, the first time we execute this code, we won’t have saved anything in the data store, so the objects list will be empty.

Next, just as with all the other applications in this chapter, we register to be notified when the application is about to move out of the active state (either by being shuffled to the background or exited completely), so we can save any changes the user has made to the data:

    let app = UIApplication.shared()
    NotificationCenter.default.addObserver(self,
              selector: #selector(UIApplicationDelegate.applicationWillResignActive(_:)),
              name: NSNotification.Name.UIApplicationWillResignActive,
              object: app)

Finally, the catch clause prints any error that is thrown from the fetch() method :

       } catch {
            // Error thrown from executeFetchRequest()
            print("There was an error in executeFetchRequest(): (error)")
       }

Now let’s look at applicationWillResignActive() . We start out the same way as the previous method: by getting a reference to the application delegate and using that to get a pointer to our application’s default managed object context :

        let appDelegate =
            UIApplication.shared().delegate as! AppDelegate
        let context = appDelegate.managedObjectContext

After that, we go into a loop that executes once for each text field, and then get a reference to the correct field:

        for i in 0 ..< lineFields.count {
            let textField = lineFields[i]

Next, we create our fetch request for our Line entry. We need to find out if there’s already a managed object in the persistent store that corresponds to this field, so we create a predicate that identifies the correct object for the field by using the index of the text field as the record key :

let request: NSFetchRequest<NSFetchRequestResult> =
let pred = Predicate(format: "%K = %d", ViewController.lineNumberKey, i)
request.predicate = pred

Now we execute the fetch request against the context. As before, we wrap this code in a do-catch block so that we can report any error that is reported by Core Data:

            do {
                let objects = try context.fetch(request)

After that, we declare a variable called theLineof type NSManagedObject that will reference the managed object for this row’s data. We may not have previously stored any data for this row, so at this point, we don’t know whether we’re going to get a managed object for it from the persistent store. For that reason, theLine needs to be declared as optional. But for convenience, we’ll make it force unwrapped, since we’re going to use the insertNewObject ( forEntityName: inManagedObjectContext:) method to create a new managed object for this row in the persistent store if we didn’t get one. We’ll use that managed object to initialize theLine in that case:

                var theLine:NSManagedObject! = objects.first as? NSManagedObject
                if theLine == nil {
                    // No existing data for this row – insert a new managed object for it
                    theLine =
                        NSEntityDescription.insertNewObject(
                                forEntityName: ViewController.lineEntityName,
                                into: context)
                                as NSManagedObject

Next, we use key-value coding to set the line number and text for this managed object. We log any error that was caught in the catch clause:

   theLine.setValue(i, forKey: ViewController.lineNumberKey)
   theLine.setValue(textField.text, forKey: ViewController.lineTextKey)

Finally, once we’re finished looping, we tell the context to save its changes:

    appDelegate.saveContext()

That’s it. Build and run the app to make sure it works. The Core Data version of your application should behave exactly the same as the previous versions.