Mac Developer Library

Developer

CoreData Framework Reference NSAtomicStore Class Reference

Options
Deployment Target:

On This Page
Language:

NSAtomicStore

NSAtomicStore is an abstract superclass that you can subclass to create a Core Data atomic store. It provides default implementations of some utility methods. You use a custom atomic store if you have a custom file format that you want to integrate with a Core Data application. More...

Inheritance


Conforms To


Import Statement


import CoreData @import CoreData;

Availability


Available in OS X v10.5 and later.
  • Returns an atomic store, initialized with the given arguments.

    Declaration

    Swift

    init(persistentStoreCoordinator coordinator: NSPersistentStoreCoordinator?, configurationName configurationName: String?, URL url: NSURL, options options: [NSObject : AnyObject]?)

    Objective-C

    - (instancetype)initWithPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator configurationName:(NSString *)configurationName URL:(NSURL *)url options:(NSDictionary *)options

    Parameters

    coordinator

    A persistent store coordinator.

    configurationName

    The name of the managed object model configuration to use.

    url

    The URL of the store to load. This value must not be nil.

    options

    A dictionary containing configuration options.

    Return Value

    An atomic store, initialized with the given arguments, or nil if the store could not be initialized.

    Discussion

    You typically do not invoke this method yourself; it is invoked by the persistent store coordinator during addPersistentStoreWithType:configuration:URL:options:error:, both when a new store is created and when an existing store is opened.

    In your implementation, you should check whether a file already exists at url; if it does not, then you should either create a file here or ensure that your load: method does not fail if the file does not exist.

    Any subclass of NSAtomicStore 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 you to securely create reservation files in known locations which can then be passed to Core Data to construct stores. You may choose to create zero-length reservation files during initWithPersistentStoreCoordinator:configurationName:URL:options: or load:. If you do so, you must remove the reservation file if the store is removed from the coordinator before it is saved.

    You should ensure that you load metadata during initialization and set it using setMetadata:.

    Special Considerations

    You must invoke super’s implementation to ensure that the store is correctly initialized.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Loads the cache nodes for the receiver.

    Declaration

    Swift

    func load(_ error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)load:(NSError **)error

    Parameters

    error

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

    Return Value

    YEStrue if the cache nodes were loaded correctly, otherwise NOfalse.

    Discussion

    You override this method to to load the data from the URL specified in initWithPersistentStoreCoordinator:configurationName:URL:options: and create cache nodes for the represented objects. You must respect the configuration specified for the store, as well as the options.

    Any subclass of NSAtomicStore 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 you to securely create reservation files in known locations which can then be passed to Core Data to construct stores. You may choose to create zero-length reservation files during initWithPersistentStoreCoordinator:configurationName:URL:options: or load:. If you do so, you must remove the reservation file if the store is removed from the coordinator before it is saved.

    Special Considerations

    You must override this method.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Returns a managed object ID from the reference data for a specified entity.

    Declaration

    Swift

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

    Objective-C

    - (NSManagedObjectID *)objectIDForEntity:(NSEntityDescription *)entity referenceObject:(id)data

    Parameters

    entity

    An entity description object.

    data

    Reference data for which the managed object ID is required.

    Return Value

    The managed object ID from the reference data for a specified entity

    Discussion

    You use this method to create managed object IDs which are then used to create cache nodes for information being loaded into the store.

    Special Considerations

    You should not override this method.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Registers a set of cache nodes with the receiver.

    Declaration

    Swift

    func addCacheNodes(_ cacheNodes: NSSet)

    Objective-C

    - (void)addCacheNodes:(NSSet *)cacheNodes

    Parameters

    cacheNodes

    A set of cache nodes.

    Discussion

    You should invoke this method in a subclass during the call to load: to register the loaded information with the store.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Returns a new cache node for a given managed object.

    Declaration

    Swift

    func newCacheNodeForManagedObject(_ managedObject: NSManagedObject) -> NSAtomicStoreCacheNode

    Objective-C

    - (NSAtomicStoreCacheNode *)newCacheNodeForManagedObject:(NSManagedObject *)managedObject

    Parameters

    managedObject

    A managed object.

    Return Value

    A new cache node for managedObject.

    Discussion

    This method is invoked by the framework during a save operation, once for each newly-inserted managed object. It should pull information from the managed object and return a cache node containing the information (the node will be registered by the framework).

    Special Considerations

    You must override this method.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Returns a new reference object for a given managed object.

    Declaration

    Swift

    func newReferenceObjectForManagedObject(_ managedObject: NSManagedObject) -> AnyObject

    Objective-C

    - (id)newReferenceObjectForManagedObject:(NSManagedObject *)managedObject

    Parameters

    managedObject

    A managed object. At the time this method is called, it has a temporary ID.

    Return Value

    A new reference object for managedObject.

    Discussion

    This method is invoked by the framework after a save operation on a managed object context, once for each newly-inserted managed object. The value returned is used to create a permanent ID for the object and must be unique for an instance within its entity's inheritance hierarchy (in this store).

    Special Considerations

    You must override this method.

    This method must return a stable (unchanging) value for a given object, otherwise Save As and migration will not work correctly. This means that you can use arbitrary numbers, UUIDs, or other random values only if they are persisted with the raw data. If you cannot save the originally-assigned reference object with the data, then the method must derive the reference object from the managed object’s values. For more details, see Atomic Store Programming Topics.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Updates the given cache node using the values in a given managed object.

    Declaration

    Swift

    func updateCacheNode(_ node: NSAtomicStoreCacheNode, fromManagedObject managedObject: NSManagedObject)

    Objective-C

    - (void)updateCacheNode:(NSAtomicStoreCacheNode *)node fromManagedObject:(NSManagedObject *)managedObject

    Parameters

    node

    The cache node to update.

    managedObject

    The managed object with which to update node.

    Discussion

    This method is invoked by the framework after a save operation on a managed object context, once for each updated NSManagedObject instance.

    You override this method in a subclass to take the information from managedObject and update node.

    Special Considerations

    You must override this method.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Method invoked before the store removes the given collection of cache nodes.

    Declaration

    Swift

    func willRemoveCacheNodes(_ cacheNodes: NSSet)

    Objective-C

    - (void)willRemoveCacheNodes:(NSSet *)cacheNodes

    Parameters

    cacheNodes

    The set of cache nodes to remove.

    Discussion

    This method is invoked by the store before the call to save: with the collection of cache nodes marked as deleted by a managed object context. You can override this method to track the nodes which will not be made persistent in the save: method.

    You should not invoke this method directly in a subclass.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

    See Also

    – save:

  • Saves the cache nodes.

    Declaration

    Swift

    func save(_ error: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)save:(NSError **)error

    Parameters

    error

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

    Discussion

    You override this method to make persistent the necessary information from the cache nodes to the URL specified for the receiver.

    Special Considerations

    You must override this method.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Returns the set of cache nodes registered with the receiver.

    Declaration

    Swift

    func cacheNodes() -> NSSet

    Objective-C

    - (NSSet *)cacheNodes

    Return Value

    The set of cache nodes registered with the receiver.

    Discussion

    You should modify this collection using addCacheNodes:: and willRemoveCacheNodes:.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Returns the cache node for a given managed object ID.

    Declaration

    Swift

    func cacheNodeForObjectID(_ objectID: NSManagedObjectID) -> NSAtomicStoreCacheNode?

    Objective-C

    - (NSAtomicStoreCacheNode *)cacheNodeForObjectID:(NSManagedObjectID *)objectID

    Parameters

    objectID

    A managed object ID.

    Return Value

    The cache node for objectID.

    Discussion

    This method is normally used by cache nodes to locate related cache nodes (by relationships).

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Returns the reference object for a given managed object ID.

    Declaration

    Swift

    func referenceObjectForObjectID(_ objectID: NSManagedObjectID) -> AnyObject

    Objective-C

    - (id)referenceObjectForObjectID:(NSManagedObjectID *)objectID

    Parameters

    objectID

    A managed object ID.

    Return Value

    The reference object for objectID.

    Discussion

    Subclasses should invoke this method to extract the reference data from the object ID for each cache node if the data is to be made persistent.

    Import Statement

    import CoreData

    Availability

    Available in OS X v10.5 and later.

  • Returns the metadata for the receiver.

    Declaration

    Objective-C

    - (NSDictionary *)metadata

    Return Value

    The metadata for the receiver.

    Discussion

    NSAtomicStore provides a default dictionary of metadata. This dictionary contains the store type and identifier (NSStoreTypeKey and NSStoreUUIDKey) as well as store versioning information. Subclasses must ensure that the metadata is saved along with the store data.

    Import Statement

    See Also

    metadata (NSPersistentStore)

  • Sets the metadata for the receiver.

    Declaration

    Objective-C

    - (void)setMetadata:(NSDictionary *)storeMetadata

    Parameters

    storeMetadata

    The metadata for the receiver.

    Import Statement

    See Also

    – metadata