NSMergePolicy Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/CoreData.framework
Availability
Available in OS X v10.7 and later.
Companion guide
Declared in
NSManagedObjectContext.h
NSMergePolicy.h

Overview

You use a merge policy object to resolve conflicts between the persistent store and in-memory versions of managed objects.

A conflict is a mismatch between state held at two different layers in the Core Data stack. A conflict can arise when you save a managed object context when you have stale data at some layer. There are two places in which a conflict may occur:

Conflicts are represented by instances of NSMergeConflict.

Tasks

Using a Merge Policy

Properties

mergeType

The merge type. (read-only)

@property(readonly) NSMergePolicyType mergeType
Availability
  • Available in OS X v10.7 and later.
Declared In
NSMergePolicy.h

Instance Methods

initWithMergeType:

Returns a merge policy initialized with a given policy type.

- (id)initWithMergeType:(NSMergePolicyType)ty
Parameters
ty

A merge policy type.

Return Value

A merge policy initialized with a given policy type.

Discussion

If you override this method in a subclass, you should invoke the superclass’s implementation with the merge policy that is closest to the behavior you want.

  • This will make it easier to use the superclass’s implementation of resolveConflicts:error: and then customize the results.

  • Due to the complexity of merging to-many relationships, this class is designed with the expectation that you call super as the base implementation.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSMergePolicy.h

resolveConflicts:error:

Resolves the conflicts in a given list.

- (BOOL)resolveConflicts:(NSArray *)list error:(NSError **)error
Parameters
list

An array of merge conflicts (instances of NSMergeConflict).

error

If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YES if the conflicts were resolved successfully, otherwise NO.

Discussion

If you override this method in a subclass, you should typically invoke the superclass’s implementation in addition to performing your own operations.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSMergePolicy.h

Constants

Merge Policies

Merge policy singleton objects that define standard ways to handle conflicts during a save operation.

id NSErrorMergePolicy;
id NSMergeByPropertyStoreTrumpMergePolicy;
id NSMergeByPropertyObjectTrumpMergePolicy;
id NSOverwriteMergePolicy;
id NSRollbackMergePolicy;
Constants
NSErrorMergePolicy

This policy causes a save to fail if there are any merge conflicts.

This is the default policy for all managed object contexts.

In the case of failure, the save method returns with an error with a userInfo dictionary that contains the object IDs of the objects that had conflicts (NSInsertedObjectsKey, NSUpdatedObjectsKey).

Available in OS X v10.4 and later.

Declared in NSMergePolicy.h.

NSMergeByPropertyStoreTrumpMergePolicy

This policy merges conflicts between the persistent store’s version of the object and the current in-memory version, giving priority to external changes.

The merge occurs by individual property. For properties that have been changed in both the external source and in memory, the external changes trump the in-memory ones.

Available in OS X v10.4 and later.

Declared in NSManagedObjectContext.h.

NSMergeByPropertyObjectTrumpMergePolicy

This policy merges conflicts between the persistent store’s version of the object and the current in-memory version, giving priority to in-memory changes.

The merge occurs by individual property. For properties that have been changed in both the external source and in memory, the in-memory changes trump the external ones.

Available in OS X v10.4 and later.

Declared in NSMergePolicy.h.

NSOverwriteMergePolicy

This policy overwrites state in the persistent store for the changed objects in conflict.

Changed objects’ current state is forced upon the persistent store.

Available in OS X v10.4 and later.

Declared in NSManagedObjectContext.h.

NSRollbackMergePolicy

This policy discards in-memory state changes for objects in conflict.

The persistent store’s version of the objects’ state is used.

Available in OS X v10.4 and later.

Declared in NSManagedObjectContext.h.

Discussion

The default policy is the NSErrorMergePolicy. It is the only policy that requires action to correct any conflicts; the other policies make a save go through silently by making changes following their rules.

NSMergePolicyType

Constants to define merge policy types.

enum {
   NSErrorMergePolicyType                      = 0x00,
   NSMergeByPropertyStoreTrumpMergePolicyType  = 0x01,
   NSMergeByPropertyObjectTrumpMergePolicyType = 0x02,
   NSOverwriteMergePolicyType                  = 0x03,
   NSRollbackMergePolicyType                   = 0x04
};
typedef NSUInteger NSMergePolicyType;
Constants
NSErrorMergePolicyType

Specifies a policy that causes a save to fail if there are any merge conflicts.

Available in OS X v10.7 and later.

Declared in NSMergePolicy.h.

NSMergeByPropertyStoreTrumpMergePolicyType

Specifies a policy that merges conflicts between the persistent store’s version of the object and the current in-memory version, giving priority to external changes.

Available in OS X v10.7 and later.

Declared in NSMergePolicy.h.

NSMergeByPropertyObjectTrumpMergePolicyType

Specifies a policy that merges conflicts between the persistent store’s version of the object and the current in-memory version, giving priority to in-memory changes.

Available in OS X v10.7 and later.

Declared in NSMergePolicy.h.

NSOverwriteMergePolicyType

Specifies a policy that overwrites state in the persistent store for the changed objects in conflict.

Available in OS X v10.7 and later.

Declared in NSMergePolicy.h.

NSRollbackMergePolicyType

Specifies a policy that discards in-memory state changes for objects in conflict.

Available in OS X v10.7 and later.

Declared in NSMergePolicy.h.