Next Page > Hide TOC

NSPersistentDocument Class Reference

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

Note that NSPersistentDocument does not support some standard document behavior, in particular NSPersistentDocument does not support file wrappers. “Save To…” and Autosave are not directly supported—Core Data cannot save to a store and maintain the same changed state in the managed object context, all the while maintaining an unsaved stack as the current 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.

Tasks

Managing the Persistence Objects

• – managedObjectContext
• – managedObjectModel
• – setManagedObjectContext:
• – configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:
• – persistentStoreTypeForFileType:

Undo Support

• – hasUndoManager
• – setHasUndoManager:
• – setUndoManager:
• – isDocumentEdited

Document Content Management

• – readFromURL:ofType:error:
• – revertToContentsOfURL:ofType:error:
• – writeToURL:ofType:forSaveOperation:originalContentsURL:error:

Deprecated

• – configurePersistentStoreCoordinatorForURL:ofType:error: Deprecated in Mac OS X v10.5

Instance Methods

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 Mac OS X v10.5 and later.

Declared In

hasUndoManager

Returns YES.

- (BOOL)hasUndoManager

Return Value

YES.

Special Considerations

You should not override this method.

See Also

• – managedObjectContext

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

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 Mac OS X v10.4 and later.

See Also

• – managedObjectModel

Related Sample Code

• Departments and Employees
• QTMetadataEditor

Declared In

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 Mac 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 Mac OS X v10.4 and later.

See Also

• – managedObjectContext

Declared In

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 (see Storing Document Types Information in a Property List).

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:

Declared In

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 Mac OS X v10.4 and later.

See Also

• – revertToContentsOfURL:ofType:error:
• – writeToURL:ofType:forSaveOperation:originalContentsURL:error:
• – configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:

Declared In

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 Mac OS X v10.4 and later.

See Also

• – readFromURL:ofType:error:
• – writeToURL:ofType:forSaveOperation:originalContentsURL:error:

Related Sample Code

• QTMetadataEditor

Declared In

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

• – managedObjectContext

setManagedObjectContext:

Sets the receiver’s managed object context.

- (void)setManagedObjectContext:(NSManagedObjectContext *)managedObjectContext

Parameters

managedObjectContext

The managed object context for the receiver.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – managedObjectContext
• – managedObjectModel

Declared In

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

• – managedObjectContext

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 Mac OS X v10.4 and later.

See Also

• – readFromURL:ofType:error:
• – revertToContentsOfURL:ofType:error:
• – configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:

Declared In

Next Page > Hide TOC