NSMigrationManager Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/CoreData.framework
Availability
Available in OS X v10.5 and later.
Companion guide
Core Data Model Versioning and Data Migration Programming Guide
Declared in
NSMigrationManager.h

Overview

Instances of NSMigrationManager perform a migration of data from one persistent store to another using a given mapping model.

Tasks

Initializing a Manager

Performing Migration Operations

Monitoring Migration Progress

Working with Source and Destination Instances

Getting Information About a Migration Manager

Using Store-Specific Migration Managers

Instance Methods

associateSourceInstance:withDestinationInstance:forEntityMapping:

Associates a given source instance with an array of destination instances for a given property mapping.

- (void)associateSourceInstance:(NSManagedObject *)sourceInstance withDestinationInstance:(NSManagedObject *)destinationInstance forEntityMapping:(NSEntityMapping *)entityMapping
Parameters
sourceInstance

A source managed object.

destinationInstance

The destination manage object for sourceInstance.

entityMapping

The entity mapping to use to associate sourceInstance with the object in destinationInstances.

Discussion

Data migration is performed as a three-stage process (first create the data, then relate the data, then validate the data). You use this method to associate data between the source and destination stores, in order to allow for relationship creation or fix-up after the creation stage.

This method is called in the default implementation of NSEntityMigrationPolicy’s createDestinationInstancesForSourceInstance:entityMapping:manager:error: method.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

cancelMigrationWithError:

Cancels the migration with a given error.

- (void)cancelMigrationWithError:(NSError *)error
Parameters
error

An error object that describes the reason why the migration is canceled.

Discussion

You can invoke this method from anywhere in the migration process to abort the migration. Calling this method causes migrateStoreFromURL:type:options:withMappingModel:toDestinationURL:destinationType:destinationOptions:error: to abort the migration and return error—you should provide an appropriate error to indicate the reason for the cancellation.

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

currentEntityMapping

Returns the entity mapping currently being processed.

- (NSEntityMapping *)currentEntityMapping
Return Value

The entity mapping currently being processed.

Discussion

Each entity is processed a total of three times (instance creation, relationship creation, validation).

Special Considerations

You can observe this value using key-value observing.

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

destinationContext

Returns the managed object context the receiver uses for writing the destination persistent store.

- (NSManagedObjectContext *)destinationContext
Return Value

The managed object context the receiver uses for writing the destination persistent store.

Discussion

This context is created on demand as part of the initialization of the Core Data stacks used for migration.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

destinationEntityForEntityMapping:

Returns the entity description for the destination entity of a given entity mapping.

- (NSEntityDescription *)destinationEntityForEntityMapping:(NSEntityMapping *)mEntity
Parameters
mEntity

An entity mapping.

Return Value

The entity description for the destination entity of mEntity.

Discussion

Entity mappings do not store the actual description objects, but rather the name and version information of the entity.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

destinationInstancesForEntityMappingNamed:sourceInstances:

Returns the managed object instances created in the destination store for a named entity mapping for a given array of source instances.

- (NSArray *)destinationInstancesForEntityMappingNamed:(NSString *)mappingName sourceInstances:(NSArray *)sourceInstances
Parameters
mappingName

The name of an entity mapping in use.

sourceInstances

A array of managed objects in the source store.

Return Value

An array containing the managed object instances created in the destination store for the entity mapping named mappingName for sourceInstances. If sourceInstances is nil, all of the destination instances created by the specified property mapping are returned.

Special Considerations

This method throws an NSInvalidArgumentException exception if mappingName is not a valid mapping name.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

destinationModel

Returns the destination model for the receiver.

- (NSManagedObjectModel *)destinationModel
Return Value

The destination model for the receiver.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

initWithSourceModel:destinationModel:

Initializes a migration manager instance with given source and destination models.

- (id)initWithSourceModel:(NSManagedObjectModel *)sourceModel destinationModel:(NSManagedObjectModel *)destinationModel
Parameters
sourceModel

The source managed object model for the migration manager.

destinationModel

The destination managed object model for the migration manager.

Return Value

A migration manager instance initialized to migrate data in a store that uses sourceModel to a store that uses destinationModel.

Discussion

You specify the mapping model in the migration method, migrateStoreFromURL:type:options:withMappingModel:toDestinationURL:destinationType:destinationOptions:error:.

Special Considerations

This is the designated initializer for NSMigrationManager.

Although validation of the models is performed during migrateStoreFromURL:type:options:withMappingModel:toDestinationURL:destinationType:destinationOptions:error:, as with NSPersistentStoreCoordinator once models are added to the migration manager they are immutable and cannot be altered.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

mappingModel

Returns the mapping model for the receiver.

- (NSMappingModel *)mappingModel
Return Value

The mapping model for the receiver.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

migrateStoreFromURL:type:options:withMappingModel:toDestinationURL:destinationType:destinationOptions:error:

Migrates of the store at a given source URL to the store at a given destination URL, performing all of the mappings specified in a given mapping model.

- (BOOL)migrateStoreFromURL:(NSURL *)sourceURL type:(NSString *)sStoreType options:(NSDictionary *)sOptions withMappingModel:(NSMappingModel *)mappings toDestinationURL:(NSURL *)dURL destinationType:(NSString *)dStoreType destinationOptions:(NSDictionary *)dOptions error:(NSError **)error
Parameters
sourceURL

The location of an existing persistent store. A store must exist at this URL.

sStoreType

The type of store at sourceURL (see NSPersistentStoreCoordinator for possible values).

sOptions

A dictionary of options for the source (see NSPersistentStoreCoordinator for possible values).

mappings

The mapping model to use to effect the migration.

dURL

The location of the destination store.

dStoreType

The type of store at dURL (see NSPersistentStoreCoordinator for possible values).

dOptions

A dictionary of options for the destination (see NSPersistentStoreCoordinator for possible values).

error

If an error occurs during the validation or migration, upon return contains an NSError object that describes the problem.

Return Value

YES if the migration proceeds without errors during the compatibility checks or migration, otherwise NO.

Discussion

This method performs compatibility checks on the source and destination models and the mapping model.

Special Considerations

If a store does not exist at the destination URL (dURL), one is created; otherwise, the migration appends to the existing store.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

migrationProgress

Returns a number from 0 to 1 that indicates the proportion of completeness of the migration.

- (float)migrationProgress
Return Value

A number from 0 to 1 that indicates the proportion of completeness of the migration. If a migration is not taking place, returns 1.

Special Considerations

You can observe this value using key-value observing.

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

reset

Resets the association tables for the migration.

- (void)reset
Special Considerations

This method does not reset the source or destination contexts.

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

setUserInfo:

Sets the user info for the receiver.

- (void)setUserInfo:(NSDictionary *)dict
Parameters
dict

The user info for the receiver.

Discussion

You can use the user info dictionary to aid the customization of your migration process.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

setUsesStoreSpecificMigrationManager:

Sets whether the receiver tries to use a store specific migration manager to perform the migration.

- (void)setUsesStoreSpecificMigrationManager:(BOOL)flag;
Parameters
flag

YES to use a store-specific migration manager, otherwise NO.

Discussion

A store-specific migration manager class is not guaranteed to perform any of the migration manager delegate callbacks or update values for the observable properties.

The default value is YES.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSMigrationManager.h

sourceContext

Returns the managed object context the receiver uses for reading the source persistent store.

- (NSManagedObjectContext *)sourceContext
Return Value

The managed object context the receiver uses for reading the source persistent store.

Discussion

This context is created on demand as part of the initialization of the Core Data stacks used for migration.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

sourceEntityForEntityMapping:

Returns the entity description for the source entity of a given entity mapping.

- (NSEntityDescription *)sourceEntityForEntityMapping:(NSEntityMapping *)mEntity
Parameters
mEntity

An entity mapping.

Return Value

The entity description for the source entity of mEntity.

Discussion

Entity mappings do not store the actual description objects, but rather the name and version information of the entity.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

sourceInstancesForEntityMappingNamed:destinationInstances:

Returns the managed object instances in the source store used to create a given destination instance for a given property mapping.

- (NSArray *)sourceInstancesForEntityMappingNamed:(NSString *)mappingName destinationInstances:(NSArray *)destinationInstances
Parameters
mappingName

The name of an entity mapping in use.

destinationInstances

A array of managed objects in the destination store.

Return Value

An array containing the managed object instances in the source store used to create destinationInstances using the entity mapping named mappingName. If destinationInstances is nil, all of the source instances used to create the destination instance for this property mapping are returned.

Special Considerations

This method throws an NSInvalidArgumentException exception if mappingName is not a valid mapping name.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

sourceModel

Returns the source model for the receiver.

- (NSManagedObjectModel *)sourceModel
Return Value

The source model for the receiver.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

userInfo

Returns the user info for the receiver.

- (NSDictionary *)userInfo
Return Value

The user info for the receiver.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSMigrationManager.h

usesStoreSpecificMigrationManager

Returns a Boolean value that indicates whether the receiver tries to use a store specific migration manager to perform the migration.

- (BOOL)usesStoreSpecificMigrationManager
Return Value

YES if the receiver uses a store-specific migration manager, otherwise NO.

Discussion

For more discussion, see setUsesStoreSpecificMigrationManager:.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSMigrationManager.h


© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)

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