NSPersistentDocument Class Reference

Inherits from
NSDocument : NSObject
Conforms to
NSUserInterfaceValidations (NSDocument)
NSFilePresenter (NSDocument)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.4 and later.
Declared in
NSPersistentDocument.h
Companion guides
Document-Based App Programming Guide for Mac
Core Data Programming Guide
Related sample code

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:

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.

Tasks

Managing the Persistence Objects

Undo Support

Document Content Management

Deprecated

Instance Methods

canAsynchronouslyWriteToURL:ofType:forSaveOperation:

Returns NO.

- (BOOL)canAsynchronouslyWriteToURL:(NSURL *)url ofType:(NSString *)typeName forSaveOperation:(NSSaveOperationType)saveOperation
Return Value

NO.

Discussion

NSPersistentDocument does not support asynchronous save operations. You should not override this method.

configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:

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

- (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

YES if the method completes successfully, otherwise NO.

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).

Availability
  • Available in OS X v10.5 and later.
Declared In
NSPersistentDocument.h

hasUndoManager

Returns YES.

- (BOOL)hasUndoManager
Return Value

YES.

Special Considerations

You should not override this method.

See Also

isDocumentEdited

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

- (BOOL)isDocumentEdited
Return Value

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

See Also

managedObjectContext

Returns the managed object context for the receiver.

- (NSManagedObjectContext *)managedObjectContext
Return Value

The managed object context for the receiver.

Discussion

If a managed object context for the receiver does not exist, one is created automatically. You override this method to customize the creation of the persistence stack.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSPersistentDocument.h

managedObjectModel

Returns the receiver’s managed object model.

- (id)managedObjectModel
Return Value

The receiver’s managed object model, used to configure the receiver’s persistent store coordinator.

Discussion

By default the Core Data framework creates a merged model from all models in the application bundle ([NSBundle mainBundle]). You can override this method to 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];

Normally you would cache the model as an instance variable. If all your document instances use the same model, however, you can increase the efficiency of this method by caching a single instance, as illustrated in the following example. 

- (id)managedObjectModel {
    static id sharedModel = nil;
    if (sharedModel == nil) {
        sharedModel = [[super managedObjectModel] retain];
    }
    return sharedModel;
}
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.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSPersistentDocument.h

persistentStoreTypeForFileType:

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

- (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.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSPersistentDocument.h

readFromURL:ofType:error:

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

- (BOOL)readFromURL:(NSURL *)absoluteURL ofType:(NSString *)typeName error:(NSError **)outError
Parameters
absoluteURL

An URL that specifies the location from which to read the document.

typeName

The document type at absoluteURL.

outError

If absoluteURL is not valid, or the store at absoluteURL cannot be read, upon return contains an NSError object that describes the problem

Return Value

YES if absoluteURL is valid and the file is read correctly, otherwise NO.

Discussion

This method sets the URL for the persistent object store associated with the receiver’s managed object context to absoluteURL.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSPersistentDocument.h

revertToContentsOfURL:ofType:error:

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

- (BOOL)revertToContentsOfURL:(NSURL *)inAbsoluteURL ofType:(NSString *)inTypeName error:(NSError **)outError
Parameters
inAbsoluteURL

An URL object that specifies the location of the file to which to revert.

inTypeName

The type of the document at inAbsoluteURL.

outError

If the method fails to complete correctly, upon return contains an NSError object that describes the problem.

Return Value

YES if the method completes correctly, otherwise NO.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSPersistentDocument.h

setHasUndoManager:

Overridden to be a no-op.

- (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.

See Also

setManagedObjectContext:

Sets the receiver’s managed object context.

- (void)setManagedObjectContext:(NSManagedObjectContext *)managedObjectContext
Parameters
managedObjectContext

The managed object context for the receiver.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSPersistentDocument.h

setUndoManager:

Overridden to be a no-op.

- (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.

See Also

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.

- (BOOL)writeToURL:(NSURL *)absoluteURL ofType:(NSString *)typeName forSaveOperation:(NSSaveOperationType)saveOperation originalContentsURL:(NSURL *)absoluteOriginalContentsURL error:(NSError **)error
Parameters
absoluteURL

An URL that specifies the new location for the document store. It must not be a relative URL.

typeName

The document type.

saveOperation

The save operation type. See the "Constants" section in NSDocument for possible values.

absoluteOriginalContentsURL

An URL that specifies the location of the original document store.

error

If the save fails to complete correctly, upon return contains an NSError object that describes the problem.

Return Value

YES if the save completes correctly, otherwise NO.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSPersistentDocument.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-05-14)

Did this document help you? Yes It's good, but... Not helpful...