NSEntityMigrationPolicy Class Reference

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

Overview

Instances of NSEntityMigrationPolicy customize the migration process for an entity mapping.

You set the policy for an entity mapping by passing the name of the migration policy class as the argument to setEntityMigrationPolicyClassName: (typically you specify the name in the Xcode mapping model editor).

Tasks

Customizing Stages of the Mapping Life Cycle

Instance Methods

beginEntityMapping:manager:error:

Invoked by the migration manager at the start of a given entity mapping.

- (BOOL)beginEntityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error

Parameters

mapping: The mapping object in use.
manager: The migration manager performing the migration.
error: If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YES if the method completes successfully, otherwise NO.

Discussion

This method is the precursor to the creation stage. In a custom class, you can implement this method to set up any state information that will be useful for the duration of the migration.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSEntityMigrationPolicy.h

createDestinationInstancesForSourceInstance:entityMapping:manager:error:

Creates the destination instance(s) for a given source instance.

- (BOOL)createDestinationInstancesForSourceInstance:(NSManagedObject *)sInstance entityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error

Parameters

sInstance: The source instance for which to create destination instances.
mapping: The mapping object in use.
manager: The migration manager performing the migration.
error: If an error occurs, 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 by the migration manager on each source instance (as specified by the sourceExpression in the mapping) to create the corresponding destination instance(s). It also associates the source and destination instances by calling NSMigrationManager’s associateSourceInstance:withDestinationInstance:forEntityMapping: method.

Special Considerations

If you override this method and do not invoke super, you must invoke NSMigrationManager’s associateSourceInstance:withDestinationInstance:forEntityMapping: to associate the source and destination instances as required. .

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSEntityMigrationPolicy.h

createRelationshipsForDestinationInstance:entityMapping:manager:error:

Constructs the relationships between the newly-created destination instances.

- (BOOL)createRelationshipsForDestinationInstance:(NSManagedObject *)dInstance entityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error

Parameters

dInstance: The destination instance for which to create relationships.
mapping: The mapping object in use.
manager: The migration manager performing the migration.
error: If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YES if the relationships are constructed correctly, otherwise NO.

Discussion

You can use this stage to (re)create relationships between migrated objects—you use the association lookup methods on the NSMigrationManager instance to determine the appropriate relationship targets.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSEntityMigrationPolicy.h

endEntityMapping:manager:error:

Invoked by the migration manager at the end of a given entity mapping.

- (BOOL)endEntityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error

Parameters

mapping: The mapping object in use.
manager: The migration manager performing the migration.
error: If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YES if the method completes correctly, otherwise NO.

Discussion

This is the end to the given entity mapping. You can implement this method to perform any clean-up at the end of the migration (from any of the three phases of the mapping).

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSEntityMigrationPolicy.h

endInstanceCreationForEntityMapping:manager:error:

Indicates the end of the creation stage for the specified entity mapping, and the precursor to the next migration stage.

- (BOOL)endInstanceCreationForEntityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error

Parameters

mapping: The mapping object in use.
manager: The migration manager performing the migration.
error: If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YES if the relationships are constructed correctly, otherwise NO.

Discussion

You can override this method to clean up state from the creation of destination or to prepare state for the creation of relationships.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSEntityMigrationPolicy.h

endRelationshipCreationForEntityMapping:manager:error:

Indicates the end of the relationship creation stage for the specified entity mapping.

- (BOOL)endRelationshipCreationForEntityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error

Parameters

mapping: The mapping object in use.
manager: The migration manager performing the migration.
error: If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YES if the method completes correctly, otherwise NO.

Discussion

This method is invoked after createRelationshipsForDestinationInstance:entityMapping:manager:error:; you can override it to clean up state from the creation of relationships, or prepare state for custom validation in performCustomValidationForEntityMapping:manager:error:.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSEntityMigrationPolicy.h

performCustomValidationForEntityMapping:manager:error:

Invoked during the validation stage of the entity migration policy, providing the option of performing custom validation on migrated objects.

- (BOOL)performCustomValidationForEntityMapping:(NSEntityMapping *)mapping manager:(NSMigrationManager *)manager error:(NSError **)error

Parameters

mapping: The mapping object in use.
manager: The migration manager performing the migration.
error: If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YES if the method completes correctly, otherwise NO.

Discussion

This method is called before the default save validation is performed by the framework.

If you implement this method, you must manually obtain the collection of objects you are interested in validating.

Availability

Available in Mac OS X v10.5 and later.

Declared In

NSEntityMigrationPolicy.h

Constants

Value Expression Keys

Keys used in value expression right hand sides.

NSString *NSMigrationManagerKey;
NSString *NSMigrationSourceObjectKey;
NSString *NSMigrationDestinationObjectKey;
NSString *NSMigrationEntityMappingKey;
NSString *NSMigrationPropertyMappingKey;
NSString *NSMigrationEntityPolicyKey;