Class

NSPersistentDocument

A document object that can integrate with Core Data.

Declaration

class NSPersistentDocument : NSDocument

Overview

The NSPersistentDocument class is a subclass of NSDocument that is designed to easily integrate into the Core Data framework. It provides methods to access a document-wide NSManagedObjectContext object, and provides default implementations of methods to read and write files using the persistence framework. In a persistent document, the undo manager functionality is taken over by managed object context.

Standard document behavior is implemented as follows:

  • Opening a document invokes configurePersistentStoreCoordinator(for:ofType:modelConfiguration:storeOptions:) with the new URL, and adds a store of the default type (XML). Objects are loaded from the persistent store on demand through the document’s context.

  • Saving a new document adds a store of the default type with the chosen URL and invokes save: on the context. For an existing document, a save just invokes save() on the context.

  • Save As for a new document simply invokes save. For an opened document, it migrates the persistent store to the new URL and invokes save() on the context.

  • Revert resets the document’s managed object context. Objects are subsequently loaded from the persistent store on demand, as with opening a new document.

By default an NSPersistentDocument instance creates its own ready-to-use persistence stack including managed object context, persistent object store coordinator and persistent store. There is a one-to-one mapping between the document and the backing object store.

You can customize the architecture of the persistence stack by overriding the methods NSPersistentDocument and configurePersistentStoreCoordinator(for:ofType:modelConfiguration:storeOptions:). You might wish to do this, for example, to specify a particular managed object model.

Topics

Managing the Persistence Objects

var managedObjectContext: NSManagedObjectContext?

The managed object context for the document.

var managedObjectModel: NSManagedObjectModel?

The managed object model of the document.

func configurePersistentStoreCoordinator(for: URL, ofType: String, modelConfiguration: String?, storeOptions: [String : Any]? = nil)

Configures the receiver’s persistent store coordinator with the appropriate stores for a given URL.

func persistentStoreType(forFileType: String) -> String

Returns the type of persistent store associated with the specified file type.

Document Content Management

func read(from: URL, ofType: String)

Sets the contents of the receiver by reading from a file of a given type located by a given URL.

func revert(toContentsOf: URL, ofType: String)

Overridden to clean up the managed object context and controllers during a revert.

func write(to: URL, ofType: String, for: NSDocument.SaveOperationType, originalContentsURL: URL?)

Saves changes in the document’s managed object context and saves the document’s persistent store to a given URL.

See Also

Documents

class NSDocumentController

An object that manages an app's documents.

class NSDocument

An abstract class that defines the interface for macOS documents.