Mac Developer Library

Developer

AppKit Framework Reference NSPersistentDocument Class Reference

Options
Deployment Target:

On This Page
Language:

NSPersistentDocument

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

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.4 and later.
  • The managed object context for the document.

    Declaration

    Swift

    var managedObjectContext: NSManagedObjectContext!

    Objective-C

    @property(strong) NSManagedObjectContext *managedObjectContext

    Discussion

    If a managed object context for the document does not exist, one is created automatically. If you want to customize the creation of the persistence stack, reimplement this property in your custom subclass and use your implementation to create the appropriate objects.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The managed object model of the document. (read-only)

    Declaration

    Swift

    var managedObjectModel: AnyObject! { get }

    Objective-C

    @property(readonly, strong) id managedObjectModel

    Discussion

    By default the Core Data framework creates a merged model from all models in the application bundle ([NSBundle mainBundle]). You can reimplement this property and return a specific model to use to create persistent stores. A typical implementation might include code similar to the following fragment:

    • NSBundle *bundle = [NSBundle bundleForClass:[self class]];
    • NSString *path = [bundle pathForResource:@"MyModel" ofType:@"mom"];
    • NSURL *url = [NSURL fileURLWithPath:path];
    • NSManagedObjectModel *model = [[NSManagedObjectModel alloc] initWithContentsOfURL:url];

    Special Considerations

    In applications built on OS X v10.4, by default the Core Data framework creates a merged model from all the models found in the application bundle and the frameworks against which the application is linked.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func configurePersistentStoreCoordinatorForURL(_ url: NSURL!, ofType fileType: String!, modelConfiguration configuration: String?, storeOptions storeOptions: [NSObject : AnyObject]!, error error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)configurePersistentStoreCoordinatorForURL:(NSURL *)url ofType:(NSString *)fileType modelConfiguration:(NSString *)configuration storeOptions:(NSDictionary *)storeOptions error:(NSError **)error

    Parameters

    url

    An URL that specifies the location of the document's store.

    fileType

    The document type.

    configuration

    The name of the managed object model configuration to use. (The managed object model is associated with the persistent store coordinator.) Pass nil if you do not want to specify a configuration.

    storeOptions

    Options for the store. See “Store Options” in NSPersistentStoreCoordinator for possible values.

    error

    If the method does not complete successfully, upon return contains an NSError object that describes the problem.

    Return Value

    YEStrue if the method completes successfully, otherwise NOfalse.

    Discussion

    This method is invoked automatically when an existing document is opened. You override this method to customize creation of a persistent store for a given document or store type. You can retrieve the persistent store coordinator with the following code:

    • [[self managedObjectContext] persistentStoreCoordinator];

    You can override this method to create the store to save to or load from (invoked from within the other NSDocument methods to read/write files), which gives developers the ability to load/save from/to different persistent store types (default type is XML).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func persistentStoreTypeForFileType(_ fileType: String!) -> String!

    Objective-C

    - (NSString *)persistentStoreTypeForFileType:(NSString *)fileType

    Parameters

    fileType

    A document file type.

    Return Value

    The type of persistent store associated with fileType. For possible values, see NSPersistentStoreCoordinator.

    Discussion

    You set the persistent store type in the application's property list.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns YEStrue.

    Declaration

    Objective-C

    - (BOOL)hasUndoManager

    Return Value

    YEStrue.

    Special Considerations

    You should not override this method.

  • Overridden to be a no-op.

    Declaration

    Objective-C

    - (void)setHasUndoManager:(BOOL)flag

    Parameters

    flag

    This value is ignored.

    Special Considerations

    You should not override this method. The persistent document uses the managed object context’s undo manager.

  • Overridden to be a no-op.

    Declaration

    Objective-C

    - (void)setUndoManager:(NSUndoManager *)undoManager

    Parameters

    undoManager

    This value is ignored.

    Special Considerations

    You should not override this method. The persistent document uses the managed object context’s undo manager.

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

    Declaration

    Objective-C

    - (BOOL)isDocumentEdited

    Return Value

    YEStrue if the receiver’s managed object context, or editors registered with the context, have uncommitted changes, otherwise NOfalse.