Class

NSPersistentDocument

A document object that can integrate with Core Data.

Declaration

@interface 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 configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error: 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 configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:. You might wish to do this, for example, to specify a particular managed object model.

Topics

Managing the Persistence Objects

managedObjectContext

The managed object context for the document.

managedObjectModel

The managed object model of the document.

- configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:

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

- persistentStoreTypeForFileType:

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

Undo Support

- hasUndoManager

Returns YES.

- setHasUndoManager:

Overridden to be a no-op.

- setUndoManager:

Overridden to be a no-op.

- isDocumentEdited

Returns a Boolean value that indicates whether the receiver’s managed object context, or editors registered with the context, have uncommitted changes.

Document Content Management

- readFromURL:ofType:error:

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

- revertToContentsOfURL:ofType:error:

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

- writeToURL:ofType:forSaveOperation:originalContentsURL:error:

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

Deprecated

- configurePersistentStoreCoordinatorForURL:ofType:error:

Configures the receiver’s persistent store coordinator for a given URL and document type.

Deprecated

Relationships

Inherits From

See Also

Documents

Developing a Document-Based App

Write an app that creates, manages, edits, and saves text documents.

NSDocumentController

An object that manages an app's documents.

NSDocument

An abstract class that defines the interface for macOS documents.