NSIncrementalStore Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreData.framework |
| Availability | Available in iOS 5.0 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.
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
-
– loadMetadata: -
– executeRequest:withContext:error: -
– newValuesForObjectWithID:withContext:error: -
– newValueForRelationship:forObjectWithID:withContext:error: -
– obtainPermanentIDsForObjects:error:
Optional Methods
-
+ identifierForNewStoreAtURL: -
– managedObjectContextDidRegisterObjectsWithIDs: -
– managedObjectContextDidUnregisterObjectsWithIDs:
Methods That Should Not Be Overridden
Class Methods
identifierForNewStoreAtURL:
Returns the identifier for the store at a given URL.
Parameters
- storeURL
The URL of a persistent store.
Return Value
The identifier for the store at storeURL.
Availability
- Available in iOS 5.0 and later.
Declared In
NSIncrementalStore.hInstance Methods
executeRequest:withContext:error:
Returns a value as appropriate for the given request, or nil if the request cannot be completed.
Parameters
- request
A fetch request.
- context
The managed object context used to execute request.
- error
If an error occurs, on return contains an
NSErrorobject 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, orNSDictionaryResultType, 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 anNSNumberwhose 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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hloadMetadata:
Loads the metadata for the store.
Parameters
- error
If an error occurs, on return contains an
NSErrorobject 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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hmanagedObjectContextDidRegisterObjectsWithIDs:
Indicates that objects identified by a given array of object IDs are in use in a managed object context.
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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hmanagedObjectContextDidUnregisterObjectsWithIDs:
Indicates that objects identified by a given array of object IDs are no longer being used by a managed object context.
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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hnewObjectIDForEntity:referenceObject:
Returns a new object ID that uses given data as the key.
Parameters
- entity
The entity for the new object ID.
- data
The data 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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hnewValueForRelationship:forObjectWithID:withContext:error:
Returns the relationship for the given relationship of the object with a given object ID.
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
NSErrorobject 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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hnewValuesForObjectWithID:withContext:error:
Returns an incremental store node encapsulating the persistent external values of the object with a given object ID.
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
NSErrorobject 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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hobtainPermanentIDsForObjects:error:
Returns an array containing the object IDs for a given array of newly-inserted objects.
Parameters
- array
An array of newly-inserted objects.
- error
If an error occurs, upon return contains an
NSErrorobject 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 iOS 5.0 and later.
Declared In
NSIncrementalStore.hreferenceObjectForObjectID:
Returns the reference data used to construct a given object ID.
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 iOS 5.0 and later.
Declared In
NSIncrementalStore.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-10-12)