NSAtomicStore Class Reference

Inherits from
NSPersistentStore : NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/CoreData.framework
Availability
Available in iOS 3.0 and later.
Declared in
NSAtomicStore.h
Companion guides
Atomic Store Programming Topics
Core Data Programming Guide

Overview

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.

The atomic stores are all intended to handle data sets that can be expressed in memory. The atomic store API favors simplicity over performance.

Subclassing Notes

Methods to Override

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

load:Loads the cache nodes for the receiver.
newCacheNodeForManagedObject:Returns a new cache node for a given managed object.
newReferenceObjectForManagedObject:Returns a new reference object for a given managed object.
save:Saves the cache nodes.
updateCacheNode:fromManagedObject:Updates the given cache node using the values in a given managed object.

These are in addition to the methods you must override for a subclass of NSPersistentStore:

typeReturns the type string of the receiver.
identifierReturns the unique identifier for the receiver.
setIdentifier:Sets the unique identifier for the receiver.
metadataReturns the metadata for the receiver.
metadataForPersistentStoreWithURL:error:Returns the metadata from the persistent store at the given URL.
setMetadata:forPersistentStoreWithURL:error:Sets the metadata for the store at a given URL.

Tasks

Initializing a Store

Loading a Store

Updating Cache Nodes

Saving a Store

Utility Methods

Managing Metadata

Instance Methods

addCacheNodes:

Registers a set of cache nodes with the receiver.

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

Availability
  • Available in iOS 3.0 and later.
Declared In
NSAtomicStore.h

cacheNodeForObjectID:

Returns the cache node for a given managed object ID.

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

Availability
  • Available in iOS 3.0 and later.
Declared In
NSAtomicStore.h

cacheNodes

Returns the set of cache nodes registered with the receiver.

- (NSSet *)cacheNodes
Return Value

The set of cache nodes registered with the receiver.

Discussion

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

Availability
  • Available in iOS 3.0 and later.
Declared In
NSAtomicStore.h

initWithPersistentStoreCoordinator:configurationName:URL:options:

Returns an atomic store, initialized with the given arguments.

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

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
NSAtomicStore.h

load:

Loads the cache nodes for the receiver.

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

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

Return Value

YES if the cache nodes were loaded correctly, otherwise NO.

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.

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
NSAtomicStore.h

metadata

Returns the metadata for the receiver.

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

See Also

newCacheNodeForManagedObject:

Returns a new cache node for a given managed object.

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

Availability
  • Available in iOS 3.0 and later.
Declared In
NSAtomicStore.h

newReferenceObjectForManagedObject:

Returns a new reference object for a given managed object.

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

Availability
  • Available in iOS 3.0 and later.
Declared In
NSAtomicStore.h

objectIDForEntity:referenceObject:

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

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

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
NSAtomicStore.h

referenceObjectForObjectID:

Returns the reference object for a given managed object ID.

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

Availability
  • Available in iOS 3.0 and later.
Declared In
NSAtomicStore.h

save:

Saves the cache nodes.

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

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
NSAtomicStore.h

setMetadata:

Sets the metadata for the receiver.

- (void)setMetadata:(NSDictionary *)storeMetadata
Parameters
storeMetadata

The metadata for the receiver.

See Also

updateCacheNode:fromManagedObject:

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

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

Availability
  • Available in iOS 3.0 and later.
Declared In
NSAtomicStore.h

willRemoveCacheNodes:

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

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

Availability
  • Available in iOS 3.0 and later.
See Also
Declared In
NSAtomicStore.h


© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-04-23)

Did this document help you? Yes It's good, but... Not helpful...