Mac Developer Library

Developer

CoreData Framework Reference NSMigrationManager Class Reference

Options
Deployment Target:

On This Page
Language:

NSMigrationManager

Inheritance


Conforms To


Import Statement


Swift

import CoreData

Objective-C

@import CoreData;

Availability


Available in OS X v10.5 and later.

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

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

    Declaration

    Swift

    func migrateStoreFromURL(_ sourceURL: NSURL, type sStoreType: String, options sOptions: [NSObject : AnyObject]?, withMappingModel mappings: NSMappingModel?, toDestinationURL dURL: NSURL, destinationType dStoreType: String, destinationOptions dOptions: [NSObject : AnyObject]?, error error: NSErrorPointer) -> Bool

    Objective-C

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

    YEStrue if the migration proceeds without errors during the compatibility checks or migration, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Resets the association tables for the migration.

    Declaration

    Swift

    func reset()

    Objective-C

    - (void)reset

    Special Considerations

    This method does not reset the source or destination contexts.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Cancels the migration with a given error.

    Declaration

    Swift

    func cancelMigrationWithError(_ error: NSError)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • A number between 0 and 1 that indicates the proportion of completeness of the migration. (read-only)

    Declaration

    Swift

    var migrationProgress: Float { get }

    Objective-C

    @property(readonly) float migrationProgress

    Special Considerations

    If a migration is not taking place, this property is 1. You can observe this value using key-value observing.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • The entity mapping currently being processed. (read-only)

    Declaration

    Swift

    var currentEntityMapping: NSEntityMapping { get }

    Objective-C

    @property(readonly, strong) NSEntityMapping *currentEntityMapping

    Discussion

    Each entity is processed a total of three times—instance creation, relationship creation, and validation.

    Special Considerations

    You can observe this value using key-value observing.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func associateSourceInstance(_ sourceInstance: NSManagedObject, withDestinationInstance destinationInstance: NSManagedObject, forEntityMapping entityMapping: NSEntityMapping)

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func destinationInstancesForEntityMappingNamed(_ mappingName: String, sourceInstances sourceInstances: [AnyObject]?) -> [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func sourceInstancesForEntityMappingNamed(_ mappingName: String, destinationInstances destinationInstances: [AnyObject]?) -> [AnyObject]

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var usesStoreSpecificMigrationManager: Bool

    Objective-C

    @property BOOL usesStoreSpecificMigrationManager

    Return Value

    YEStrue if the receiver uses a store-specific migration manager, otherwise NOfalse.

    Discussion

    YEStrue if the receiver uses a store-specific migration manager, otherwise NOfalse. The default value is YEStrue.

    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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.