Mac Developer Library

Developer

Core Data Framework Reference NSIncrementalStore Class Reference

Options
Deployment Target:

On This Page
Language:

NSIncrementalStore

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.

  • Loads the metadata for the store.

    Declaration

    Swift

    func loadMetadata() throws

    Objective-C

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

    Parameters

    error

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

    Return Value

    YEStrue if the metadata was correctly loaded, otherwise NOfalse.

    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.

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

    Declaration

    Swift

    func executeRequest(_ request: NSPersistentStoreRequest, withContext context: NSManagedObjectContext?) throws -> AnyObject

    Objective-C

    - (id)executeRequest:(NSPersistentStoreRequest *)request withContext:(NSManagedObjectContext *)context error:(NSError * _Nullable *)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 it is NSManagedObjectResultType, NSManagedObjectIDResultType, or NSDictionaryResultType, the method should return an array containing all objects in the store matching the request.

    • If it is NSCountResultType, the method should return an array containing an NSNumber whose value is the count of of all objects in the store matching the request.

    • If the request is a save request, the method should return an empty array.

    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.

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

    Declaration

    Swift

    func newValuesForObjectWithID(_ objectID: NSManagedObjectID, withContext context: NSManagedObjectContext) throws -> NSIncrementalStoreNode

    Objective-C

    - (NSIncrementalStoreNode *)newValuesForObjectWithID:(NSManagedObjectID *)objectID withContext:(NSManagedObjectContext *)context error:(NSError * _Nullable *)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.

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

    Declaration

    Swift

    func newValueForRelationship(_ relationship: NSRelationshipDescription, forObjectWithID objectID: NSManagedObjectID, withContext context: NSManagedObjectContext?) throws -> AnyObject

    Objective-C

    - (id)newValueForRelationship:(NSRelationshipDescription *)relationship forObjectWithID:(NSManagedObjectID *)objectID withContext:(NSManagedObjectContext *)context error:(NSError * _Nullable *)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.

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

    Declaration

    Swift

    func obtainPermanentIDsForObjects(_ array: [NSManagedObject]) throws -> [NSManagedObjectID]

    Objective-C

    - (NSArray<NSManagedObjectID *> *)obtainPermanentIDsForObjects:(NSArray<NSManagedObject *> *)array error:(NSError * _Nullable *)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.