UIManagedDocument Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 5.0 and later.
Declared in
UIManagedDocument.h
Companion guides

Overview

UIManagedDocument is a concrete subclass of UIDocument that integrates with Core Data. When you initialize a managed document, you specify the URL for the document location. The document object then creates a Core Data stack to use to access the document’s persistent store using a managed object model from the application’s main bundle. See “Supporting Document-Based Apps in iCloud” in iCloud Programming Guide for Core Data for implementation strategies and troubleshooting steps.

UIManagedDocument performs all the basic set-up you need for Core Data, and in some cases you may use instances of UIManagedDocument directly (without a need to subclass). You can supply configuration options for the creation of the coordinator using persistentStoreOptions, and for the model using modelConfiguration. You can also perform additional customization by creating a subclass of UIManagedDocument:

Handling Errors

To enable your app to observe and handle errors in saving and validating a managed document, you must subclass the UIManagedDocument class and override one or both of the following two inherited methods from the UIDocument class:

Overriding is required because, otherwise, the only information your app receives on error is the UIDocumentStateChangedNotification notification, which does not contain a userInfo dictionary and so does not convey specific error information.

Tasks

Managing the Core Data Stack

Customizing Read and Write Operations

Naming the Persistent Store File

Properties

managedObjectContext

The document’s managed object context. (read-only)

@property(nonatomic, retain, readonly) NSManagedObjectContext *managedObjectContext
Discussion

The document automatically creates a managed object context using its persistent store coordinator.

Special Considerations

You must not use the document’s managed object context in writeAdditionalContent:toURL:originalContentsURL:error:, or any of the asynchronous UIDocument methods.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

managedObjectModel

The document’s managed object model. (read-only)

@property(nonatomic, retain, readonly) NSManagedObjectModel *managedObjectModel
Discussion

Persistent documents always have a managed object model. The default model is the union of all models in the main bundle. You can specify a configuration to use with modelConfiguration. You can subclass UIManagedDocument to override this method if you need custom behavior.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

modelConfiguration

A model configuration name to be passed when configuring the persistent store.

@property(nonatomic, copy) NSString *modelConfiguration
Discussion

By default, this value is nil.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

persistentStoreOptions

Options used when creating the document’s persistent store.

@property(nonatomic, copy) NSDictionary *persistentStoreOptions
Discussion

By default, this value is nil.

To support automatic migration, you might pass a dictionary like that shown in the following example.

NSDictionary *options = [NSDictionary dictionaryWithObjectsAndKeys:
    [NSNumber numberWithBool:YES], NSMigratePersistentStoresAutomaticallyOption,
    [NSNumber numberWithBool:YES], NSInferMappingModelAutomaticallyOption, nil];
<#Managed document instance#>.persistentStoreOptions = options;
Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

Class Methods

persistentStoreName

Returns the name for the persistent store file inside the document’s file package.

+ (NSString *)persistentStoreName
Return Value

The name for the persistent store file inside the document’s file package.

Discussion

This path component is appended to the document URL provided by UIDocument. The default name is persistentStore.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

Instance Methods

additionalContentForURL:error:

Handles writing non-Core Data content to the additional content directory in the document’s file package.

- (id)additionalContentForURL:(NSURL *)absoluteURL error:(NSError **)error
Parameters
absoluteURL

The URL for the additional content directory in the document’s file package.

error

Upon return, if a problem occurs, contains an error object that describes the problem.

Return Value

An object that contains the additional content for the document at absoluteURL, or nil if there is a problem.

Discussion

You override this method to perform to manage non-Core Data content to be stored in the additional content directory in the document’s file package.

If you implement this method, it is invoked automatically by contentsForType:error:. The returned object is passed to writeAdditionalContent:toURL:originalContentsURL:error:.

There is no need to invoke super’s implementation.

Special Considerations

A return value of nil indicates an error condition. To avoid generating an exception, you must return a value from this method. If it is not always the case that there will be additional content, you should return a sentinel value (for example, an NSNull instance) that you check for in writeAdditionalContent:toURL:originalContentsURL:error:.

The object returned from this method is passed to writeAdditionalContent:toURL:originalContentsURL:error:. Because writeAdditionalContent:toURL:originalContentsURL:error: is executed on a different thread, you must ensure that the object you return is thread-safe. For example, you might return an NSData object containing an archive of the state you want to capture.

Additional content is not supported on iCloud.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

configurePersistentStoreCoordinatorForURL:ofType:modelConfiguration:storeOptions:error:

Creates or loads the document’s persistent store.

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

The URL for the persistent store.

fileType

The document’s file type.

configuration

The managed object model configuration to use.

storeOptions

The options used to configure the persistent store coordinator.

error

Upon return, if a problem occurs, contains an error object that describes the problem.

Return Value

YES if configuration is successful, otherwise NO.

Discussion

You can override this method if you want customize the creation or loading of the document’s persistent store. For example, you can perform post-migration clean-up—if your application needs to migrate store data to use a new version of the managed object model, you can override this method to make additional modifications to the store after migration.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

persistentStoreTypeForFileType:

Returns the Core Data store type for a given document file type.

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

The document file type.

Return Value

The persistent store type for fileType.

Discussion

Override this method to specify a persistent store type for a given document type.

The default returns NSSQLiteStoreType.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

readAdditionalContentFromURL:error:

Handles reading non-Core Data content in the additional content directory in the document’s file package.

- (BOOL)readAdditionalContentFromURL:(NSURL *)absoluteURL error:(NSError **)error
Parameters
absoluteURL

The URL for the additional content directory in the document’s file package.

error

Upon return, if a problem occurs, contains an error object that describes the problem.

Return Value

YES if the read operation is successful, otherwise NO.

Discussion

You override this method to read non-Core Data content from the additional content directory in the document’s file package.

If you implement this method, it is invoked automatically by readFromURL:error:.

There is no need to invoke super’s implementation.

Special Considerations

Additional content is not supported on iCloud.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h

writeAdditionalContent:toURL:originalContentsURL:error:

Handles writing non-Core Data content to the document’s file package.

- (BOOL)writeAdditionalContent:(id)content toURL:(NSURL *)absoluteURL originalContentsURL:(NSURL *)absoluteOriginalContentsURL error:(NSError **)error
Parameters
content

An object that represents the additional content for the document.

This is the object returned from additionalContentForURL:error:.

absoluteURL

The URL to which to write the additional content.

absoluteOriginalContentsURL

The current URL of the document that is being saved.

error

Upon return, if a problem occurs, contains an error object that describes the problem.

Return Value

YES if the write operation is successful, otherwise NO.

Discussion

You override this method to perform to write non-Core Data content in the additional content directory in the document’s file package. There are several issues to consider:

Special Considerations

Additional content is not supported on iCloud.

Availability
  • Available in iOS 5.0 and later.
Declared In
UIManagedDocument.h