Mac Developer Library

Developer

CoreData 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.

Inheritance


Conforms To


Import Statement


Swift

import CoreData

Objective-C

@import CoreData;

Availability


Available in OS X v10.7 and later.
  • Loads the metadata for the store.

    Declaration

    Swift

    func loadMetadata(_ error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)loadMetadata:(NSError **)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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    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, error error: NSErrorPointer) -> AnyObject?

    Objective-C

    - (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 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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    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, error error: NSErrorPointer) -> NSIncrementalStoreNode?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    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?, error error: NSErrorPointer) -> AnyObject?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    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: [AnyObject], error error: NSErrorPointer) -> [AnyObject]?

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.

  • Returns the identifier for the store at a given URL.

    Declaration

    Swift

    class func identifierForNewStoreAtURL(_ storeURL: NSURL) -> AnyObject

    Objective-C

    + (id)identifierForNewStoreAtURL:(NSURL *)storeURL

    Parameters

    storeURL

    The URL of a persistent store.

    Return Value

    The identifier for the store at storeURL.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func managedObjectContextDidRegisterObjectsWithIDs(_ objectIDs: [AnyObject])

    Objective-C

    - (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:.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func managedObjectContextDidUnregisterObjectsWithIDs(_ objectIDs: [AnyObject])

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func newObjectIDForEntity(_ entity: NSEntityDescription, referenceObject data: AnyObject) -> NSManagedObjectID

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func referenceObjectForObjectID(_ objectID: NSManagedObjectID) -> AnyObject

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import CoreData;

    Swift

    import CoreData

    Availability

    Available in OS X v10.7 and later.