NSEntityMigrationPolicy 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
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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 OS X v10.5 and later.
See Also
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;
Constants
NSMigrationManagerKey

Key for the migration manager.

To access this key in a custom value expression string in the Xcode mapping model editor use $manager.

Available in OS X v10.5 and later.

Declared in NSEntityMigrationPolicy.h.

NSMigrationSourceObjectKey

Key for the source object.

To access this key in a custom value expression string in the Xcode mapping model editor use $source.

Available in OS X v10.5 and later.

Declared in NSEntityMigrationPolicy.h.

NSMigrationDestinationObjectKey

Key for the destination object.

To access this key in a custom value expression string in the Xcode mapping model editor use $destination.

Available in OS X v10.5 and later.

Declared in NSEntityMigrationPolicy.h.

NSMigrationEntityMappingKey

Key for the entity mapping object.

To access this key in a custom value expression string in the Xcode mapping model editor use $entityMapping.

Available in OS X v10.5 and later.

Declared in NSEntityMigrationPolicy.h.

NSMigrationPropertyMappingKey

Key for the property mapping object.

To access this key in a custom value expression string in the Xcode mapping model editor use $propertyMapping.

Available in OS X v10.5 and later.

Declared in NSEntityMigrationPolicy.h.

NSMigrationEntityPolicyKey

Key for the entity migration policy object.

To access this key in a custom value expression string in the Xcode mapping model editor use $entityPolicy.

Available in OS X v10.6 and later.

Declared in NSEntityMigrationPolicy.h.

Discussion

You can use these keys in the right hand sides of a value expression.



© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-02-24)

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