A document object that can integrate with Core Data.


@interface NSPersistentDocument : NSDocument


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.


Managing the Persistence Objects


The managed object context for the document.


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.


- configurePersistentStoreCoordinatorForURL:ofType:error:

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



Inherits From

See Also


Developing a Document-Based App

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


An abstract class that defines the interface for macOS documents.


An object that manages an app's documents.