NSIncrementalStore 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
NSIncrementalStore.h

Overview

NSIncrementalStore is an abstract superclass defining the API through which Core Data communicates with a store. This interface is designed to allow you to create persistent stores which load and save data incrementally, allowing for the management of large and/or shared datasets. See Incremental Store Programming Guide for an implementation strategy and best practices when implementing your own incremental store.

Subclassing Notes

Methods to Override

In a subclass of NSIncrementalStore, you must override the following methods to provide behavior appropriate for your store:

There is no need to override the methods that you must otherwise override for a subclass of NSPersistentStore.

Tasks

Required Methods

Optional Methods

Methods That Should Not Be Overridden

Class Methods

identifierForNewStoreAtURL:

Returns the identifier for the store at a given URL.

+ (id)identifierForNewStoreAtURL:(NSURL *)storeURL
Parameters
storeURL

The URL of a persistent store.

Return Value

The identifier for the store at storeURL.

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

Instance Methods

executeRequest:withContext:error:

Returns a value as appropriate for the given request, or nil if the request cannot be completed.

- (id)executeRequest:(NSPersistentStoreRequest *)request withContext:(NSManagedObjectContext *)context error:(NSError **)error
Parameters
request

A fetch request.

context

The managed object context used to execute request.

error

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

Return Value

A value as appropriate for request, or nil if the request cannot be completed

Discussion

The value to return depends on the result type (see resultType) of request:

If the save request contains nil values for the inserted/updated/deleted/locked collections; you should treat it as a request to save the store metadata.

You should implement this method conservatively, and expect that unknown request types may at some point be passed to the method. The correct behavior in these cases is to return nil and an error.

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

loadMetadata:

Loads the metadata for the store.

- (BOOL)loadMetadata:(NSError **)error
Parameters
error

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

Return Value

YES if the metadata was correctly loaded, otherwise NO.

Discussion

In your implementation of this method, you must validate that the URL used to create the store is usable (the location exists and if necessary is writable, the schema is compatible, and so on) and return an error if there is an issue.

Any subclass of NSIncrementalStore which is file-based must be able to handle being initialized with a URL pointing to a zero-length file. This serves as an indicator that a new store is to be constructed at the specified location and allows applications using the store to securely create reservation files in known locations.

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

managedObjectContextDidRegisterObjectsWithIDs:

Indicates that objects identified by a given array of object IDs are in use in a managed object context.

- (void)managedObjectContextDidRegisterObjectsWithIDs:(NSArray *)objectIDs
Parameters
objectIDs

An array of object IDs.

Discussion

This method and managedObjectContextDidUnregisterObjectsWithIDs: allow managed object contexts to communicate interest in the row data of specific objects in a manner akin to reference counting. For more details, see managedObjectContextDidUnregisterObjectsWithIDs:.

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

managedObjectContextDidUnregisterObjectsWithIDs:

Indicates that objects identified by a given array of object IDs are no longer being used by a managed object context.

- (void)managedObjectContextDidUnregisterObjectsWithIDs:(NSArray *)objectIDs
Parameters
objectIDs

An array of object IDs.

Discussion

This method is the counterpart to managedObjectContextDidRegisterObjectsWithIDs:.

Passing an object ID in the object IDs array of managedObjectContextDidRegisterObjectsWithIDs: is akin to incrementing the object ID’s reference count by 1; passing an object ID in the object IDs array of managedObjectContextDidUnregisterObjectsWithIDs: is akin to decrementing the object ID’s reference count by 1. It is only when an object ID’s reference count is 0 that no contexts indicate that they are using the corresponding managed object. (Object IDs start with a reference count of 0.)

For example, if the register methods is invoked on two occasions when the object IDs array contains a given object ID, and the unregister method is invoked once when the object IDs array contains that object ID, then a context is still using the object with the given ID.

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

newObjectIDForEntity:referenceObject:

Returns a new object ID that uses given data as the key.

- (NSManagedObjectID *)newObjectIDForEntity:(NSEntityDescription *)entity referenceObject:(id)data
Parameters
entity

The entity for the new object ID.

data

An object of type NSString or NSNumber to use as the key.

Return Value

A new object ID for an instance of the entity specified by entity and that uses data as the key.

Discussion

You should not override this method.

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

newValueForRelationship:forObjectWithID:withContext:error:

Returns the relationship for the given relationship of the object with a given object ID.

- (id)newValueForRelationship:(NSRelationshipDescription *)relationship forObjectWithID:(NSManagedObjectID *)objectID withContext:(NSManagedObjectContext *)context error:(NSError **)error
Parameters
relationship

The relationship for which values are requested.

objectID

The ID of the object for which values are requested.

context

The managed object context into which values will be returned.

error

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

Return Value

The value of the relationship specified relationship of the object with object ID objectID, or nil if an error occurs.

Discussion

If the relationship is a to-one, the method should return an NSManagedObjectID instance that identifies the destination, or an instance of NSNull if the relationship value is nil.

If the relationship is a to-many, the method should return a collection object containing NSManagedObjectID instances to identify the related objects. Using an NSArray instance is preferred because it will be the most efficient. A store may also return an instance of NSSet or NSOrderedSet; an instance of NSDictionary is not acceptable.

If an object with object ID objectID cannot be found, the method should return nil and—if error is not NULL—create and return an appropriate error object in error.

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

newValuesForObjectWithID:withContext:error:

Returns an incremental store node encapsulating the persistent external values of the object with a given object ID.

- (NSIncrementalStoreNode *)newValuesForObjectWithID:(NSManagedObjectID *)objectID withContext:(NSManagedObjectContext *)context error:(NSError **)error
Parameters
objectID

The ID of the object for which values are requested.

context

The managed object context into which values will be returned.

error

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

Return Value

An incremental store node encapsulating the persistent external values of the object with object ID objectID, or nil if the corresponding object cannot be found.

Discussion

The returned node should include all attributes values and may include to-one relationship values as instances of NSManagedObjectID.

If an object with object ID objectID cannot be found, the method should return nil and—if error is not NULL—create and return an appropriate error object in error.

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

obtainPermanentIDsForObjects:error:

Returns an array containing the object IDs for a given array of newly-inserted objects.

- (NSArray *)obtainPermanentIDsForObjects:(NSArray *)array error:(NSError **)error
Parameters
array

An array of newly-inserted objects.

error

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

Return Value

An array containing the object IDs for the objects in array.

The returned array must return the object IDs in the same order as the objects appear in array.

Discussion

This method is called before executeRequest:withContext:error: with a save request, to assign permanent IDs to newly-inserted objects.

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

referenceObjectForObjectID:

Returns the reference data used to construct a given object ID.

- (id)referenceObjectForObjectID:(NSManagedObjectID *)objectID
Parameters
objectID

An object ID created by the receiver.

Return Value

The reference data used to construct objectID.

Discussion

This method raises an NSInvalidArgumentException if the object ID was not created by the receiving store.

You should not override this method.

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